1wificonfig(1M) System Administration Commands wificonfig(1M)
2
3
4
6 wificonfig - WLAN configuration
7
9 wificonfig [-R root_path] [-i interface] autoconf
10 [wait={n|forever}]
11
12
13 wificonfig [-R root_path] [-i interface] connect profile
14 [wait={n|forever}]
15
16
17 wificonfig [-R root_path] [-i interface] connect essid
18 [wait={n|forever}]
19
20
21 wificonfig [-R root_path] [-i interface] disconnect
22
23
24 wificonfig [-R root_path] [-i interface] getparam
25 [parameter []...]
26
27
28 wificonfig [-R root_path] [-i interface] setparam
29 [parameter=value []...]
30
31
32 wificonfig [-R root_path] [-i interface] restoredef
33
34
35 wificonfig [-R root_path] [-i interface] scan
36
37
38 wificonfig [-R root_path] [-i interface] showstatus
39
40
41 wificonfig [-R root_path] [-i interface] setwepkey 1|2|3|4
42
43
44 wificonfig [-R root_path] createprofile profile
45 [parameter=value []...]
46
47
48 wificonfig [-R root_path] deleteprofile profile1
49 [profile2 []...]
50
51
52 wificonfig [-R root_path] showprofile [profile]
53
54
55 wificonfig [-R root_path] setprofilewepkey profile 1|2|3|4
56
57
58 wificonfig [-R root_path] getprofileparam profile
59 [parameter []...]
60
61
62 wificonfig [-R root_path] setprofileparam
63 [parameter=value []...]
64
65
66 wificonfig [-R root_path] history
67
68
69 wificonfig [-R root_path] listprefer
70
71
72 wificonfig [-R root_path] removeprefer profile
73
74
75 wificonfig [-R root_path] setprefer profile [n]
76
77
79 wificonfig defines a set of subcommands and parameters to configure
80 WiFi interfaces in the system. A driver may support all parameters or a
81 subset of these parameters.
82
83
84 wificonfig uses rbac(5) to control user access to the interface. Only
85 users with the "solaris.network.wifi.config" authorization can manage a
86 WiFi interface, while only users with "solaris.network.wifi.wep"autho‐
87 rizations can configure the WEP (Wired Equivalent Privacy) key. Other
88 users can only read parameters from the interface. By default, the
89 "solaris.network.wifi.config" and "solaris.network.wifi.wep" authoriza‐
90 tions are not granted to any user apart from root.
91
92
93 Wificonfig comes in two classes of forms. The first class, shown as the
94 first set of synopsis combined with the optional interface name, is the
95 subcommands used to a manipulate a particular WiFi network interface.
96 The second class, shown as the second set of synopsis, is used to cre‐
97 ate and operate on WiFi Configuration Profiles. A Configuration Profile
98 allows the user to pre-specify a set of parameters which can later be
99 applied to a WiFi network interface using the connect or autoconf sub‐
100 commands.
101
102
103 In the interface subcommands, if the interface is not specified (that
104 is, the -i option is missing), wificonfig selects a random interface
105 from the known WiFi interfaces on the system. If there are multiple
106 WiFi network interfaces on the system, then the selection will be the
107 same over time as long as the number of and names of the WiFi inter‐
108 faces does not change.
109
110
111 A Configuration Profile can be created for a WLAN by using the cre‐
112 ateprofile subcommand (see the SUBCOMMANDS section). The actual WLAN
113 may be present or not.
114
115
116 wificonfig also maintains a list of Configuration Profiles called the
117 Preference List. This list makes automatic configuration possible. When
118 the autoconf subcommand is used, wificonfig tries to connect to each
119 pre-configured WLAN according to the order of the Preference List. If
120 the Preference List is empty or none of the WLANs in the Preference
121 List can be found, wificonfig uses its built-in heuristics to automati‐
122 cally configure the interface. (See the autoconf subcommand for the
123 heuristics). A few subcommands (listprefer, setprefer, removeprefer)
124 are defined to manipulate the Preference List.
125
127 The following options are supported:
128
129 -i interface Specifies a wireless network interface to do the con‐
130 figuration.
131
132
133 -R root_path Defines the full path name of a directory to use as the
134 root_path. This affects the location of the private
135 files where wificonfig stores the Configuration Pro‐
136 files and WEP keys.
137
138
139 OPERANDS
140 The following operand is supported:
141
142 profile The name of a WiFi profile. It can be a string between 1 and
143 32 characters. However, "all", "{preference}", "{history}",
144 "{active_profile}", and any strings contained in brackets,
145 such as "[foo]", are not allowed as a profile name.
146
147
148 SUBCOMMANDS
149 The following subcommands are supported:
150
151 autoconf [wait={n|forever}]
152
153 Configures the interface automatically. The interface is configured
154 according to the previously saved Preference List found in
155 /etc/inet/wifi. wificonfig first gets a list of available WLANs by
156 scanning the radio. It then compares the list of available WLANs
157 with the Preference List. If the Preference List is empty, or if
158 none of the WLANs in the Preference List can be found, wificonfig
159 chooses a WLAN to connect to using the following priorities: 1) the
160 WLANs without encryption, 2) the WLANs with stronger signal
161 strength, and 3) the WLANs with higher transmit rates.
162
163 If the WLANs in the Preference list are available, the user can
164 specify the number of seconds to wait before autoconf returns using
165 the wait option. By default (without the wait option), autoconf
166 returns within 10 seconds. If "forever" or -1 follows the wait
167 option, wificonfig waits until the NIC is successfully connected to
168 the WLAN specified by the profile in the Preference list.
169
170 The "solaris.network.wifi.config" authorization is required for
171 this subcommand.
172
173 The WiFi device driver can not guarantee to retain the state for
174 the connection when it is not held open. For this reason, it is
175 strongly recommended that the plumb subcommand for ifconfig(1M) is
176 done before the wificonfig autoconf subcommand is given.
177
178
179 connect profile[wait={n|forever}]
180 connect essid[wait={n|forever}]
181
182 Connects to a wireless network according to a pre-configured "pro‐
183 file". If the specified Configuration Profile exists in
184 /etc/inet/wifi, the connect subcommand uses that Configuration Pro‐
185 file to configure the interface. That profile subsequently becomes
186 the current active profile of the interface after the connect sub‐
187 command succeeds. If no existing Configuration Profile matches the
188 specified name, the behavior of the connect subcommand is equiva‐
189 lent to the restoredef subcommand, except that the "essid" parame‐
190 ter is set as "profile".
191
192 If the WLANs in the Preference list are available, the user can
193 specify the number of seconds to wait before connect returns using
194 the wait option. By default (without the wait option), connect trys
195 for 10 seconds. If "forever" or -1 follows the wait option, wifi‐
196 config tries until the NIC is successfully connected to the profile
197 or essid that was specified.
198
199 The connect subcommand prints one of the following lines depending
200 on whether or not a Configuration Profile was found for the
201 specified name:
202
203 Connecting to profile <name>
204 Connecting to essid <name>
205
206
207 The "solaris.network.wifi.config" authorization is required for
208 this subcommand.
209
210 The WiFi device driver can not guarantee to retain the state for
211 the connection when it is not held open. For this reason, it is
212 strongly recommended that the plumb subcommand for ifconfig(1M) is
213 done before the wificonfig autoconf subcommand is given.
214
215
216 disconnect
217
218 Disconnects the interface from the currently associated wireless
219 network. The interface associates with none of the wireless net‐
220 works.
221
222 The "solaris.network.wifi.config" authorization is required for
223 this subcommand.
224
225
226 getparam [parameter [...]]
227 setparam [parameter=value [...]]
228
229 Gets or sets parameters in the network interface. This does not
230 affect any profile. The setprofileparam subcommand can be used to
231 set and change parameters in a profile that has already been cre‐
232 ated.
233
234 The setparam subcommand without any parameters displays the set of
235 parameters supported by the network interface, including
236 whether they are read/write or read only. The getparam subcommand
237 without any parameters displays all the parameters and their val‐
238 ues.
239
240 The setparam wepkey1|wepkey2|wepkey3|wepkey4 subcommand requires
241 the "solaris.network.wifi.wep" authorization. For all other parame‐
242 ters, the setparam subcommand requires the "solaris.net‐
243 work.wifi.config"authorization.
244
245 For example,
246
247 $ wificonfig setparam <parameter1=value1> [parameter2=value2 [...]]
248 $ wificonfig getparam <parameter1> [parameter2 [...]]
249
250
251 wificonfig currently supports the following parameters (the values
252 are case insensitive).
253
254 bssid
255
256 MAC address of the associated Access Point. The valid value is
257 a hex value of 6 bytes. The bssid can also be the IBSSID in an
258 ad-hoc configuration. If the network interface is not connected
259 to any WLAN, then the string "none" is shown instead of a 6
260 byte MAC address. Otherwise, the network interface is connected
261 to a WLAN. The default value is "none". This parameter is read-
262 only.
263
264
265 essid
266
267 Network name. The valid value is a string of up to 32 chars. If
268 essid is an empty string, the driver automatically scans and
269 joins the WLAN using the built-in heuristics. The default value
270 is an empty string.
271
272
273 bsstype
274
275 Specifies whether the Infrastructure Mode or Ad-Hoc Mode is
276 used. The valid values are "ap", "bss", or "infrastructure" to
277 join a WLAN through an Access Point, that is, to use infra‐
278 structure mode. The valid values are "ibss" or "ad-hoc" to join
279 a peer-to-peer WLAN (also named "ad-hoc"). The valid value of
280 "auto" automatically switches between the two types. The
281 default value is "infrastructure'".
282
283
284 createibss
285
286 Specifies whether to create an ad-hoc network (also called an
287 IBSS if the connect does not result in finding the desired net‐
288 work. This enables the user to start an ad-hoc network so that
289 other hosts can join. The valid values are YES to start a new
290 ad-hoc WLAN (instead of joining one) and NO to not start an ad-
291 hoc WLAN. The default value is NO. The NIC always tries to join
292 a WLAN first. If this is successful, the setting of createibss
293 is ignored.
294
295
296 channel
297
298 An integer indicating the operating frequency. This channel
299 number varies by regulatory domain. When the channel number is
300 obtained by the getparam subcommand, the value indicates the
301 actual channel the card uses to connect to the network. The
302 channel number is set by the setparam subcommand, and the value
303 is only applicable when the card is in ad-hoc mode. It indi‐
304 cates the operating channel of the IBSS. The default value is
305 the channel number on the card.
306
307
308 rates
309
310 Specifies the transmission rates. The valid values (in Mbit/s)
311 are 1, 2, 5.5, 6, 9, 11, 12, 18, 22, 24, 33, 36, 48, and 54. A
312 NIC may support multiple transmission rates depending on its
313 capability. This is the only parameter that accepts multiple
314 values. When multiple values are supplied to set this parame‐
315 ter, each value must be separated by a comma (,). See the EXAM‐
316 PLES section for details. The default values are the data rates
317 supported by the chip.
318
319
320 powermode
321
322 Specifies the power management mode. The valid values are "off"
323 to disable power management, "mps" for maximum power saving,
324 and "fast" for the best combination of speed and power saving.
325 The default value is "off".
326
327
328 authmode
329
330 Specifies the authorization type. The valid values are "open‐
331 system" for an open system, where anyone can be authenticated
332 and "shared_key" for a Shared Key authentication mode. The
333 default value is "opensystem".
334
335
336 encryption
337
338 Specifies the encryption algorithm to be used. The valid values
339 are "none" for no encryption algorithm and "wep" to turn on WEP
340 encryption. The default value is "none".
341
342
343 wepkey1|wepkey2|wepkey3|wepkey4
344
345 A maximum of 4 WEP keys (indexed 1 through 4) can be set in an
346 NIC. They are write-only parameters which can be set by the
347 setparam subcommand, but cannot be read back by the getparam
348 subcommand. WEP keys can either be set by the setwepkey or the
349 setparam subcommand. setparam uses plain text but it's script‐
350 able. See the setwepkey subcommand for more information about
351 how a WEP key is encoded. Setting WEP keys requires
352 "solaris.network.wifi.wep"authorization.
353
354 When these subcommands are used to set a WEP key, any user on
355 the system can read the key from the ps(1) output. Thus, the
356 setwepkey subcommand is recommended for setting the WEP keys
357 since it does not allow ps(1) to read the keys.
358
359
360 wepkeyindex
361
362 Specifies the encryption keys. The valid values are 1 to use
363 wepkey1, 2 to use wepkey2, 3 to use wepkey3, and 4 to use wep‐
364 key4. The default value is 1. This subcommand is only valid
365 when WEP is on.
366
367
368 signal
369
370 Specifies the strength of the received radio signal. The valid
371 values are 0 - 15 , where 0 is the weakest signal and 15 is the
372 strongest signal. This parameter is read-only and indicates the
373 radio signal strength received by the NIC.
374
375
376 radio
377
378 Specifies whether the radio is turned on or off. The valid val‐
379 ues are "on" to turn on the radio and "off" to turn off the
380 radio. The default value is "on".
381
382
383
384 restoredef
385
386 Forces the NIC to restore the network interface to use the default
387 values for all the parameters. See the getparam and setparam sub‐
388 commands for the default values of the parameters.
389
390 The "solaris.network.wifi.config" authorization is required for
391 this subcommand.
392
393
394 scan
395
396 Scans and lists the currently available WLANs.
397
398
399 showstatus
400
401 Display the basic status of a WLAN interface. If the WLAN interface
402 is connected, the basic status includes: the name of the current
403 active profile, the name of the network, the bssid, whether the
404 network is encrypted or not, and the signal strength.
405
406
407 setwepkey 1|2|3|4
408
409 Sets one of the 4 WEP encryption keys. WEP keys are used to
410 encrypt the content of the network packets which are transmitted on
411 air. There are 4 WEP keys in the NIC according to the 802.11 stan‐
412 dards. The setwepkey subcommand is used to update one of the 4 keys
413 by prompting the user for the key. The user must enter the key
414 twice. The input is not echoed. For example, to update setwepkey2:
415
416 example% wificonfig -i ath0 setwepkey 2
417 input wepkey2: < user input here>
418 confirm wepkey2: < user input here>
419
420
421 A WEP key can be 5 bytes or 13 bytes long. There are two ways to
422 enter a WEP key, by ASCII values or by hex values. If the user
423 enters 5 or 13 characters, it is considered the ASCII representa‐
424 tion of the key. If the user enters 10 or 26 characters, it is con‐
425 sidered the hex representation of the key. For example "1234" is
426 equivalent to "6162636465". If the user enters other number of
427 characters, the subcommand fails. WEP keys are write-only; they
428 cannot be read back via wificonfig.
429
430 The WEP keys can also be set in plain text form by the setparam
431 subcommand. This makes setting WEP keys scriptable (see the parame‐
432 ters of setparam for the details).
433
434 The "solaris.network.wifi.wep" authorization is required for this
435 subcommand.
436
437
438
439 The following profile subcommands are supported:
440
441 createprofile profile [parameter=value] [...]
442
443 Creates a Configuration Profile named profile off-line. The speci‐
444 fied parameters are saved as items of this Configuration Profile.
445 The user can specify a group of parameters. At a minimum, the essid
446 must be specified.
447
448 The "solaris.network.wifi.config" authorization is required for
449 this subcommand.
450
451
452 deleteprofile profile1 [profile2 [...]]
453
454 Deletes one or more Configuration Profiles according to the speci‐
455 fied names. If the specified Configuration Profile does not exist,
456 this subcommand fails. The wild-card "all" can be used to delete
457 all profiles.
458
459 The "solaris.network.wifi.config" authorization is required for
460 this subcommand.
461
462
463 showprofile [profile]
464
465 Displays the parameters in the Configuration Profile according to
466 the specified profile. WEP (wired equivalent privacy) keys are not
467 printed because they are write-only parameters. If no profile is
468 specified, all the profiles are shown.
469
470
471 setprofilewepkey 1|2|3|4
472
473 Sets one of the 4 WEP encryption keys in the specified Configura‐
474 tion Profile "profile". Like the other profile subcommands, setpro‐
475 filewepkey does not affect the configuration of a network inter‐
476 face, even if a WiFi interface is currently running with the speci‐
477 fied profile. In order for the modified profile to be applied to
478 the network interface, the connect or autoconf subcommands have
479 to be used after the profile has been updated.
480
481 Other than that difference, the usage of setprofilewepkey is the
482 same as the setwepkey subcommand. For example, to update wepkey 2
483 in profile "home":
484
485 example% wificonfig setprofilewepkey home 2
486 input wepkey2: < user input here>
487 confirm wepkey2: < user input here>
488
489
490 The "solaris.network.wifi.wep" authorization is required for this
491 subcommand.
492
493
494 getprofileparam profile [parameter] [...]]
495 setprofileparam profile [parameter=value] [...]]
496
497 Gets or sets parameters in the specified Configuration Profile
498 "profile". Like the other profile subcommands, these subcommands
499 do not affect the configuration of a network interface, even if a
500 WiFi interface is currently running with the specified pro‐
501 file. In order for the modified profile to be applied to the
502 network interface, the connect or autoconf subcommands have to be
503 used after the profile has been updated.
504
505 A getprofileparam without any parameters will display all the
506 parameters and their values.
507
508 "Solaris.network.wifi.wep" authorization is required when the set‐
509 param subcommand is used with the wepkey1|wepkey2|wepkey3|wepkey4
510 parameter. For all other parameters, the setparam subcommand
511 requires "solaris.network.wifi.config"authorization.
512
513 For example, to change the settings for the "home" Configuration
514 Profile, use:
515
516 $ wificonfig setprofileparam home <parameter1=value1> \
517 [parameter2=value2 [...]]
518 $ wificonfig getprofileparam home <parameter1> [parameter2 [...]]
519
520
521 The set of parameters and their allowed values are the same as
522 those specified for the setparam subcommand.
523
524
525 history
526
527 Lists the WLANs in the History List. wificonfig automatically
528 records the WLANs that appear in every scanning attempt. The His‐
529 tory List contains a maximum of 10 records of the most recent
530 WLANs, sorted by time. These records can be listed by using this
531 subcommand.
532
533
534 listprefer
535
536 Lists the content of the Preference List.
537
538
539 removeprefer profile
540
541 Removes one or more profiles from the Preference List. The wild-
542 card "all" can be used to delete all profiles.
543
544 The "solaris.network.wifi.config" authorization is required for
545 this subcommand.
546
547
548 setprefer profile [n]
549
550 Sets the position of a profile in the Preference List. This may add
551 or change the position of a profile in the Preference List. The
552 valid values of "n" range from 1 to 10. If "n" is missing, the
553 default value of 1 is assumed. If the specified position is already
554 occupied, the occupying profile is moved lower on the list. If "n"
555 is off the end of the list, profile is added to the end of the
556 list. The Preference List can also be created by using this subcom‐
557 mand. If the autoconf subcommand is used at a later time, wificon‐
558 fig tries to join the WLANs according to the Preference List.
559
560 The "solaris.network.wifi.config" authorization is required for
561 this subcommand.
562
563
565 Example 1 Listing the Parameters Supported by a Driver
566
567
568 To display what parameters the ath driver supports and the read/write
569 modes of the parameters:
570
571
572 % wificonfig -i ath0 setparam
573 parameter property
574 bssid read only
575 essid read/write
576 bsstype read/write
577 rates read/write
578 authmode read/write
579 encryption read/write
580 wepkeyindex read/write
581 signal read only
582
583
584
585
586 Example 2 Getting and Setting Parameters on the WiFi interface
587
588
589 To get the current rates and signal strength from the driver:
590
591
592 % wificonfig -i ath0 getparam rates signal
593 ath0:
594 rates = 1,2,5.5,11
595 signal = 10
596
597
598
599 Example 3 Managing Configuration Profiles
600
601
602 A Configuration Profile can be created offline and then connected to
603 the network with the created Configuration Profile. The following
604 series of commands creates the Configuration Profile, displays the con‐
605 tents of that profile, and connects to the network with the Configura‐
606 tion Profile:
607
608
609 % wificonfig createprofile myXXX essid=rover encryption=WEP \
610 wepkey1=12345
611 % wificonfig showprofile myXXX
612 [myXXX]
613 essid=rover
614 encryption=WEP
615 wepkey1=[secret]
616
617 % ifconfig ath0 plumb
618 % wificonfig -i ath0 connect myXXX
619
620
621
622 Example 4 Managing the Preference List
623
624
625 A profile can be added to the Preference List and then used by the
626 autoconf subcommand. The following series of commands adds a profile
627 named myXXX to the top of the Preference List, automatically connects
628 ath0 to the first available WLAN in the Preference List, and removes
629 my_neighbor from the Preference List
630
631
632 % wificonfig setprefer myXXX 1
633 % ifconfig ath0 plumb
634 % wificonfig -i ath0 autoconf
635 % wificonfig removeprefer my_neighbor
636
637
638
639 Example 5 Viewing the History List
640
641
642 To display the history of the WLANs:
643
644
645 % wificonfig history
646
647 WLAN history:
648
649 essid bssid encryption last seen
650 myXXX 00:0f:24:11:12:14 WEP Fri Sep 13 09:15:24 2004
651 my_office_ssid 00:0f:24:11:12:15 WEP Fri Sep 13 13:20:04 2004
652 my_neighbor1 00:0f:24:11:12:16 NONE Fri Sep 14 08:01:26 2004
653 my_neighbor2 00:0f:24:11:12:17 WEP Fri Sep 18 21:33:12 2004
654
655
656
657 Example 6 Automatic Configuration
658
659
660 To configure the interface according to the previously saved Preference
661 List:
662
663
664 % ifconfig ath0 plumb
665 % wificonfig -i ath0 autoconf
666
667
668
669
670 If the Preference List is empty, or none of the WLANs listed by the
671 Proference List can be found, wificonfig uses the default configura‐
672 tion, directs the interface to scan and join the WLAN using the built-
673 in heuristics specified above.
674
675
676 Example 7 Connecting To a WLAN
677
678
679 To search for a Configuration Profile with the name myXXX and configure
680 the interface accordingly:
681
682
683 % ifconfig ath0 plumb
684 % wificonfig -i ath0 connect myXXX
685
686
687
688
689 If the specified Configuration Profile does not exist, wificonfig
690 interprets it as an essid and sets ath0 to use essid myXXX, and no
691 other parameters are set.
692
693
694 Example 8 Displaying the Content of a Configuration Profile
695
696
697 To print the parameters of the previously Configured Profile named
698 my_home_ssid:
699
700
701 % wificonfig showprofile my_home_ssid
702
703
704
705 Example 9 Monitoring the link status
706
707
708 To monitor the link status:
709
710
711 % wificonfig -i ath0 showstatus
712 ath0:
713 linkstatus: not connected,
714
715
716
717
718 or
719
720
721 ath0:
722 linkstatus: connected
723 active profile: [home]
724 essid: myhome
725 bssid: 00:0b:0e:12:e2:02
726 encryption: WEP
727 signal: medium(10)
728
729
730
731 Example 10 Scanning for available networks
732
733
734 To scan for available networks:
735
736
737 % wificonfig -i ath0 scan
738 essid bssid type encryption signal
739 level
740 ietf64-secure 00:0b:0e:12:e2:02 access point WEP 9
741 roomlinx 00:40:96:a1:13:70 access point none 6
742 ietf64 00:0b:0e:13:32:00 access point none 3
743 ietf64-secure 00:0b:0e:13:32:02 access point WEP 3
744 ietf64 00:0b:0e:12:e2:00 access point none 9
745 ietf64-secure 00:0b:0e:12:e4:c2 access point WEP 8
746 ietf64 00:0b:0e:12:e4:c0 access point none 8
747 roomlinx 00:40:96:a0:aa:aa access point none 1
748 roomlinx 00:40:96:a0:ab:39 access point none 8
749
750
751
753 0 Successful operation
754
755
756 1 Fatal Error; the operation failed. For example, a connect failed
757 to associate with an Access Point.
758
759
760 2 Improper Use; help information will be printed
761
762
763 3 Minor error
764
765
767 See attributes(5) for descriptions of the following attributes:
768
769
770
771
772 ┌─────────────────────────────┬─────────────────────────────┐
773 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
774 ├─────────────────────────────┼─────────────────────────────┤
775 │Availability │SUNWwlanr, SUNWwlanu │
776 ├─────────────────────────────┼─────────────────────────────┤
777 │Interface Stability │Unstable │
778 └─────────────────────────────┴─────────────────────────────┘
779
781 ps(1), ifconfig(1M), attributes(5), ath(7D)
782
783
784
785SunOS 5.11 31 Oct 2007 wificonfig(1M)