ifconfig.8: Update to show '-d' and '-u' is mutually exclusive
[dragonfly.git] / sbin / ifconfig / ifconfig.8
1 .\" Copyright (c) 1983, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     From: @(#)ifconfig.8    8.3 (Berkeley) 1/5/94
29 .\" $FreeBSD: src/sbin/ifconfig/ifconfig.8,v 1.124 2006/10/10 09:44:08 ru Exp $
30 .\"
31 .Dd June 26, 2020
32 .Dt IFCONFIG 8
33 .Os
34 .Sh NAME
35 .Nm ifconfig
36 .Nd configure network interface parameters
37 .Sh SYNOPSIS
38 .Nm
39 .Op Fl f Ar type:format Ns Op Ar ,type:format
40 .Op Fl L
41 .Op Fl k
42 .Op Fl m
43 .Op Fl n
44 .Ar interface
45 .Op Cm create
46 .Op Ar address_family
47 .Oo
48 .Ar address
49 .Op Ar dest_address
50 .Oc
51 .Op Ar parameters
52 .Nm
53 .Op Fl n
54 .Ar interface
55 .Cm destroy
56 .Nm
57 .Fl a
58 .Op Fl L
59 .Oo
60 .Fl d |
61 .Fl u
62 .Oc
63 .Op Fl m
64 .Op Fl v
65 .Op Ar address_family
66 .Nm
67 .Fl l
68 .Oo
69 .Fl d |
70 .Fl u
71 .Oc
72 .Op Ar address_family
73 .Nm
74 .Op Fl L
75 .Oo
76 .Fl d |
77 .Fl u
78 .Oc
79 .Op Fl k
80 .Op Fl m
81 .Op Fl v
82 .Op Fl C
83 .Nm
84 .Op Fl g Ar groupname
85 .Sh DESCRIPTION
86 The
87 .Nm
88 utility is used to assign an address
89 to a network interface and/or configure
90 network interface parameters.
91 The
92 .Nm
93 utility must be used at boot time to define the network address
94 of each interface present on a machine; it may also be used at
95 a later time to redefine an interface's address
96 or other operating parameters.
97 .Pp
98 The following options are available:
99 .Bl -tag -width indent
100 .It Ar address
101 For the
102 .Tn DARPA Ns -Internet
103 family,
104 the address is either a host name present in the host name data
105 base,
106 .Xr hosts 5 ,
107 or a
108 .Tn DARPA
109 Internet address expressed in the Internet standard
110 .Dq dot notation .
111 .Pp
112 It is also possible to use the CIDR notation (also known as the
113 slash notation) to include the netmask.
114 That is, one can specify an address like
115 .Li 192.168.0.1/16 .
116 .Pp
117 For
118 .Dq inet6
119 family, it is also possible to specify the prefix length using the slash
120 notation, like
121 .Li ::1/128 .
122 See the
123 .Cm prefixlen
124 parameter below for more information.
125 .\" For the Xerox Network Systems(tm) family,
126 .\" addresses are
127 .\" .Ar net:a.b.c.d.e.f ,
128 .\" where
129 .\" .Ar net
130 .\" is the assigned network number (in decimal),
131 .\" and each of the six bytes of the host number,
132 .\" .Ar a
133 .\" through
134 .\" .Ar f ,
135 .\" are specified in hexadecimal.
136 .\" The host number may be omitted on IEEE 802 protocol
137 .\" (Ethernet, FDDI, and Token Ring) interfaces,
138 .\" which use the hardware physical address,
139 .\" and on interfaces other than the first.
140 .\" For the
141 .\" .Tn ISO
142 .\" family, addresses are specified as a long hexadecimal string,
143 .\" as in the Xerox family.
144 .\" However, two consecutive dots imply a zero
145 .\" byte, and the dots are optional, if the user wishes to (carefully)
146 .\" count out long strings of digits in network byte order.
147 .Pp
148 The link-level
149 .Pq Dq link
150 address
151 is specified as a series of colon-separated hex digits.
152 This can be used to
153 e.g.\& set a new MAC address on an Ethernet interface, though the
154 mechanism used is not Ethernet-specific.
155 If the interface is already
156 up when this option is used, it will be briefly brought down and
157 then brought back up again in order to ensure that the receive
158 filter in the underlying Ethernet hardware is properly reprogrammed.
159 .It Ar address_family
160 Specify the
161 address family
162 which affects interpretation of the remaining parameters.
163 Since an interface can receive transmissions in differing protocols
164 with different naming schemes, specifying the address family is recommended.
165 The address or protocol families currently
166 supported are
167 .Dq inet ,
168 .Dq inet6 ,
169 .Dq atalk ,
170 and
171 .Dq link .
172 The default is
173 .Dq inet .
174 .Dq ether
175 and
176 .Dq lladdr
177 are synonyms for
178 .Dq link .
179 .It Ar dest_address
180 Specify the address of the correspondent on the other end
181 of a point to point link.
182 .It Ar interface
183 This
184 parameter is a string of the form
185 .Dq name unit ,
186 for example,
187 .Dq Li ed0 .
188 .It Ar groupname
189 List the interfaces in the given group.
190 .El
191 .Pp
192 The output format of
193 .Nm
194 can be controlled with the
195 .Fl f
196 option or the
197 .Ev IFCONFIG_FORMAT
198 environment variable.
199 The format is specified as a comma-separated list of
200 .Sy type:format
201 pairs.
202 The supported
203 .Sy type
204 and its associated
205 .Sy format
206 strings are:
207 .Bl -tag -width indent
208 .It Sy addr
209 Adjust the display of inet and inet6 addresses:
210 .Bl -tag -width default
211 .It Sy default
212 Display inet and inet6 addresses in the default format, i.e.,
213 .Sy numeric .
214 .It Sy fqdn
215 Display inet and inet6 addresses as fully qualified domain names
216 .Pq FQDN .
217 .It Sy host
218 Display inet and inet6 addresses as unqualified hostnames.
219 .It Sy numeric
220 Display inet and inet6 addresses in numeric format.
221 .El
222 .It Sy ether
223 Adjust the display of link-level Ethernet (MAC) addresses:
224 .Bl -tag -width default
225 .It Sy colon
226 Separate address segments with a colon.
227 .It Sy dash
228 Separate address segments with a dash.
229 .It Sy default
230 Display Ethernet addresses in the default format, i.e.,
231 .Sy colon .
232 .El
233 .It Sy inet
234 Adjust the display of inet address subnet masks:
235 .Bl -tag -width default
236 .It Sy cidr
237 Display subnet masks in CIDR notation, for example:
238 .br
239 10.0.0.0/8 or 203.0.113.224/26
240 .It Sy default
241 Display subnet masks in the default format, i.e.,
242 .Sy hex .
243 .It Sy dotted
244 Display subnet masks in dotted quad notation, for example:
245 .br
246 255.255.0.0, 255.255.255.192
247 .It Sy hex
248 Display subnet masks in hexidecimal, for example:
249 .br
250 0xffff0000, 0xffffffc0
251 .El
252 .It Sy inet6
253 Adjust the display of inet6 address prefixes (subnet masks):
254 .Bl -tag -width default
255 .It Sy cidr
256 Display subnet prefix in CIDR notation, for example:
257 .br
258 ::1/128, fe80::1%lo0/64
259 .It Sy default
260 Display subnet prefix in the default format, i.e.,
261 .Sy numeric
262 .It Sy numeric
263 Display subnet prefix in integer format, for example:
264 .br
265 prefixlen 64
266 .El
267 .El
268 .Pp
269 The following parameters may be set with
270 .Nm :
271 .Bl -tag -width indent
272 .It Cm add
273 Another name for the
274 .Cm alias
275 parameter.
276 Introduced for compatibility
277 with
278 .Bsx .
279 .It Cm alias
280 Establish an additional network address for this interface.
281 This is sometimes useful when changing network numbers, and
282 one wishes to accept packets addressed to the old interface.
283 If the address is on the same subnet as the first network address
284 for this interface, a non-conflicting netmask must be given.
285 Usually
286 .Li 0xffffffff
287 is most appropriate.
288 .It Fl alias
289 Remove the network address specified.
290 This would be used if you incorrectly specified an alias, or it
291 was no longer needed.
292 If you have incorrectly set an NS address having the side effect
293 of specifying the host portion, removing all NS addresses will
294 allow you to respecify the host portion.
295 .It Cm anycast
296 (Inet6 only.)
297 Specify that the address configured is an anycast address.
298 Based on the current specification,
299 only routers may configure anycast addresses.
300 Anycast address will not be used as source address of any of outgoing
301 IPv6 packets.
302 .It Cm arp
303 Enable the use of the Address Resolution Protocol
304 .Pq Xr arp 4
305 in mapping
306 between network level addresses and link level addresses (default).
307 This is currently implemented for mapping between
308 .Tn DARPA
309 Internet
310 addresses and
311 .Tn IEEE
312 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses).
313 .It Fl arp
314 Disable the use of the Address Resolution Protocol
315 .Pq Xr arp 4 .
316 .It Cm staticarp
317 If the Address Resolution Protocol is enabled,
318 the host will only reply to requests for its addresses,
319 and will never send any requests.
320 .It Fl staticarp
321 If the Address Resolution Protocol is enabled,
322 the host will perform normally,
323 sending out requests and listening for replies.
324 .It Cm broadcast
325 (Inet only.)
326 Specify the address to use to represent broadcasts to the
327 network.
328 The default broadcast address is the address with a host part of all 1's.
329 .It Cm debug
330 Enable driver dependent debugging code; usually, this turns on
331 extra console error logging.
332 .It Fl debug
333 Disable driver dependent debugging code.
334 .It Cm promisc
335 Put interface into permanently promiscuous mode.
336 .It Fl promisc
337 Disable permanently promiscuous mode.
338 .It Cm delete
339 Another name for the
340 .Fl alias
341 parameter.
342 .It Cm down
343 Mark an interface
344 .Dq down .
345 When an interface is marked
346 .Dq down ,
347 the system will not attempt to
348 transmit messages through that interface.
349 If possible, the interface will be reset to disable reception as well.
350 This action does not automatically disable routes using the interface.
351 .It Cm group Ar group-name
352 Assign the interface to a
353 .Dq group .
354 Any interface can be in multiple groups.
355 .Pp
356 Cloned interfaces are members of their interface family group by default.
357 For example, a PPP interface such as
358 .Em ppp0
359 is a member of the PPP interface family group,
360 .Em ppp .
361 .\" The interface(s) that the default route(s) point to are members of the
362 .\" .Em egress
363 .\" interface group.
364 .It Cm -group Ar group-name
365 Remove the interface from the given
366 .Dq group .
367 .It Cm eui64
368 (Inet6 only.)
369 Fill interface index
370 (lowermost 64bit of an IPv6 address)
371 automatically.
372 .It Cm media Ar type
373 If the driver supports the media selection system, set the media type
374 of the interface to
375 .Ar type .
376 Some interfaces support the mutually exclusive use of one of several
377 different physical media connectors.
378 For example, a 10Mbit/s Ethernet
379 interface might support the use of either
380 .Tn AUI
381 or twisted pair connectors.
382 Setting the media type to
383 .Cm 10base5/AUI
384 would change the currently active connector to the AUI port.
385 Setting it to
386 .Cm 10baseT/UTP
387 would activate twisted pair.
388 Refer to the interfaces' driver
389 specific documentation or man page for a complete list of the
390 available types.
391 .It Cm mediaopt Ar opts
392 If the driver supports the media selection system, set the specified
393 media options on the interface.
394 The
395 .Ar opts
396 argument
397 is a comma delimited list of options to apply to the interface.
398 Refer to the interfaces' driver specific man page for a complete
399 list of available options.
400 .It Fl mediaopt Ar opts
401 If the driver supports the media selection system, disable the
402 specified media options on the interface.
403 .It Cm mode Ar mode
404 If the driver supports the media selection system, set the specified
405 operating mode on the interface to
406 .Ar mode .
407 For IEEE 802.11 wireless interfaces that support multiple operating modes
408 this directive is used to select between 802.11a
409 .Pq Cm 11a ,
410 802.11b
411 .Pq Cm 11b ,
412 and 802.11g
413 .Pq Cm 11g
414 operating modes.
415 .It Cm name Ar name
416 Set the interface name to
417 .Ar name .
418 .It Cm rss
419 If the driver supports receive side scaling,
420 enable receive side scaling on the interface.
421 .It Fl rss
422 If the driver supports receive side scaling,
423 disable receive side scaling on the interface.
424 .It Cm rxcsum , txcsum
425 If the driver supports user-configurable checksum offloading,
426 enable receive (or transmit) checksum offloading on the interface.
427 Some drivers may not be able to enable these flags independently
428 of each other, so setting one may also set the other.
429 The driver will offload as much checksum work as it can reliably
430 support, the exact level of offloading varies between drivers.
431 .It Fl rxcsum , txcsum
432 If the driver supports user-configurable checksum offloading,
433 disable receive (or transmit) checksum offloading on the interface.
434 These settings may not always be independent of each other.
435 .It Cm tso
436 If the driver supports TCP segmentation offloading,
437 enable TCP segmentation offloading on the interface.
438 .It Fl tso
439 If the driver supports TCP segmentation offloading,
440 disable TCP segmentation offloading on the interface.
441 .It Cm vlanmtu , vlanhwtag
442 If the driver offers user-configurable VLAN support, enable
443 reception of extended frames or tag processing in hardware,
444 respectively.
445 Note that this must be issued on a physical interface associated with
446 .Xr vlan 4 ,
447 not on a
448 .Xr vlan 4
449 interface itself.
450 .It Fl vlanmtu , vlanhwtag
451 If the driver offers user-configurable VLAN support, disable
452 reception of extended frames or tag processing in hardware,
453 respectively.
454 .It Cm pollcpu Ar cpu
455 Deprecated, use polling or npolling instead.
456 .It Cm polling , npolling
457 Turn on
458 .Xr polling 4
459 feature and disable interrupts on the interface, if the driver supports
460 this mode.
461 .It Fl polling , npolling
462 Turn off
463 .Xr polling 4
464 feature and enable interrupt mode on the interface.
465 .It Cm create
466 Create the specified network pseudo-device.
467 If the interface is given without a unit number, try to create a new
468 device with an arbitrary unit number.
469 If creation of an arbitrary device is successful, the new device name is
470 printed to standard output unless the interface is renamed or destroyed
471 in the same
472 .Nm
473 invocation.
474 .It Cm destroy
475 Destroy the specified network pseudo-device.
476 .It Cm plumb
477 Another name for the
478 .Cm create
479 parameter.
480 Included for
481 .Tn Solaris
482 compatibility.
483 .It Cm unplumb
484 Another name for the
485 .Cm destroy
486 parameter.
487 Included for
488 .Tn Solaris
489 compatibility.
490 .It Cm metric Ar n
491 Set the routing metric of the interface to
492 .Ar n ,
493 default 0.
494 The routing metric is used by the routing protocol
495 .Pq Xr routed 8 .
496 Higher metrics have the effect of making a route
497 less favorable; metrics are counted as additional hops
498 to the destination network or host.
499 .It Cm mtu Ar n
500 Set the maximum transmission unit of the interface to
501 .Ar n ,
502 default is interface specific.
503 The MTU is used to limit the size of packets that are transmitted on an
504 interface.
505 Not all interfaces support setting the MTU, and some interfaces have
506 range restrictions.
507 .It Cm tsolen Ar n
508 Set the maximum amount of data
509 that TCP segmentation offloading is allowed to aggregate to
510 .Ar n ,
511 the default value is interface specific.
512 This setting only takes effect on interfaces
513 that support TCP segmentation offloading.
514 .It Cm netmask Ar mask
515 .\" (Inet and ISO.)
516 (Inet only.)
517 Specify how much of the address to reserve for subdividing
518 networks into sub-networks.
519 The mask includes the network part of the local address
520 and the subnet part, which is taken from the host field of the address.
521 The mask can be specified as a single hexadecimal number
522 with a leading
523 .Ql 0x ,
524 with a dot-notation Internet address,
525 or with a pseudo-network name listed in the network table
526 .Xr networks 5 .
527 The mask contains 1's for the bit positions in the 32-bit address
528 which are to be used for the network and subnet parts,
529 and 0's for the host part.
530 The mask should contain at least the standard network portion,
531 and the subnet field should be contiguous with the network
532 portion.
533 .Pp
534 The netmask can also be specified in CIDR notation after the address.
535 See the
536 .Ar address
537 option above for more information.
538 .It Cm autoconf
539 (Inet6 only.)
540 Enable autoconfiguration.
541 .It Fl autoconf
542 Disable autoconfiguration.
543 .It Cm pltime Ar n
544 (Inet6 only.)
545 Set preferred lifetime for the address.
546 .It Cm vltime Ar n
547 (Inet6 only.)
548 Set valid lifetime for the address.
549 .It Cm prefixlen Ar len
550 (Inet6 only.)
551 Specify that
552 .Ar len
553 bits are reserved for subdividing networks into sub-networks.
554 The
555 .Ar len
556 must be integer, and for syntactical reason it must be between 0 to 128.
557 It is almost always 64 under the current IPv6 assignment rule.
558 If the parameter is omitted, 64 is used.
559 .Pp
560 The prefix can also be specified using the slash notation after the address.
561 See the
562 .Ar address
563 option above for more information.
564 .It Cm deprecated
565 (Inet6 only.)
566 Set the IPv6 deprecated address bit.
567 .It Fl deprecated
568 (Inet6 only.)
569 Clear the IPv6 deprecated address bit.
570 .It Cm tentative
571 (Inet6 only.)
572 Set the IPv6 tentative address bit.
573 .It Fl tentative
574 (Inet6 only.)
575 Clear the IPv6 tentative address bit.
576 .\" see
577 .\" Xr eon 5 .
578 .\" .It Cm nsellength Ar n
579 .\" .Pf ( Tn ISO
580 .\" only)
581 .\" This specifies a trailing number of bytes for a received
582 .\" .Tn NSAP
583 .\" used for local identification, the remaining leading part of which is
584 .\" taken to be the
585 .\" .Tn NET
586 .\" (Network Entity Title).
587 .\" The default value is 1, which is conformant to US
588 .\" .Tn GOSIP .
589 .\" When an ISO address is set in an ifconfig command,
590 .\" it is really the
591 .\" .Tn NSAP
592 .\" which is being specified.
593 .\" For example, in
594 .\" .Tn US GOSIP ,
595 .\" 20 hex digits should be
596 .\" specified in the
597 .\" .Tn ISO NSAP
598 .\" to be assigned to the interface.
599 .\" There is some evidence that a number different from 1 may be useful
600 .\" for
601 .\" .Tn AFI
602 .\" 37 type addresses.
603 .It Cm range Ar netrange
604 Under appletalk, set the interface to respond to a
605 .Ar netrange
606 of the form
607 .Ar startnet Ns - Ns Ar endnet .
608 Appletalk uses this scheme instead of
609 netmasks though
610 .Dx
611 implements it internally as a set of netmasks.
612 .It Cm remove
613 Another name for the
614 .Fl alias
615 parameter.
616 Introduced for compatibility
617 with
618 .Bsx .
619 .It Cm phase
620 The argument following this specifies the version (phase) of the
621 Appletalk network attached to the interface.
622 Values of 1 or 2 are permitted.
623 .Sm off
624 .It Cm link Op Cm 0 No - Cm 2
625 .Sm on
626 Enable special processing of the link level of the interface.
627 These three options are interface specific in actual effect, however,
628 they are in general used to select special modes of operation.
629 An example
630 of this is to enable SLIP compression, or to select the connector type
631 for some Ethernet cards.
632 Refer to the man page for the specific driver
633 for more information.
634 .Sm off
635 .It Fl link Op Cm 0 No - Cm 2
636 .Sm on
637 Disable special processing at the link level with the specified interface.
638 .It Cm compress
639 Another name for the
640 .Cm link0
641 parameter.
642 .It Cm normal
643 Another name for the
644 .Fl link0
645 parameter.
646 .It Cm noicmp
647 Another name for the
648 .Cm link1
649 parameter.
650 .It Cm monitor
651 Put the interface in monitor mode.
652 No packets are transmitted, and received packets are discarded after
653 .Xr bpf 4
654 processing.
655 .It Fl monitor
656 Take the interface out of monitor mode.
657 .It Cm up
658 Mark an interface
659 .Dq up .
660 This may be used to enable an interface after an
661 .Dq Nm Cm down .
662 It happens automatically when setting the first address on an interface.
663 If the interface was reset when previously marked down,
664 the hardware will be re-initialized.
665 .El
666 .Pp
667 The following parameters are specific to cloning
668 IEEE 802.11 wireless interfaces with the
669 .Cm create
670 request:
671 .Bl -tag -width indent
672 .It Cm wlandev Ar device
673 Use
674 .Ar device
675 as the parent for the cloned device.
676 .It Cm wlanmode Ar mode
677 Specify the operating mode for this cloned device.
678 .Ar mode
679 is one of
680 .Cm sta ,
681 .Cm ahdemo
682 (or
683 .Cm adhoc-demo ),
684 .Cm ibss ,
685 (or
686 .Cm adhoc ),
687 .Cm ap ,
688 (or
689 .Cm hostap ),
690 .Cm wds ,
691 .Cm tdma ,
692 .Cm mesh ,
693 and
694 .Cm monitor .
695 The operating mode of a cloned interface cannot be changed.
696 The
697 .Cm tdma
698 mode is actually implemented as an
699 .Cm adhoc-demo
700 interface with special properties.
701 .It Cm wlanbssid Ar bssid
702 The 802.11 mac address to use for the bssid.
703 This must be specified at create time for a legacy
704 .Cm wds
705 device.
706 .It Cm wlanaddr Ar address
707 The local mac address.
708 If this is not specified then a mac address will automatically be assigned
709 to the cloned device.
710 Typically this address is the same as the address of the parent device
711 but if the
712 .Cm bssid
713 parameter is specified then the driver will craft a unique address for
714 the device (if supported).
715 .It Cm wdslegacy
716 Mark a
717 .Cm wds
718 device as operating in ``legacy mode''.
719 Legacy
720 .Cm wds
721 devices have a fixed peer relationship and do not, for example, roam
722 if their peer stops communicating.
723 For completeness a Dynamic WDS (DWDS) interface may marked as
724 .Fl wdslegacy .
725 .It Cm bssid
726 Request a unique local mac address for the cloned device.
727 This is only possible if the device supports multiple mac addresses.
728 To force use of the parent's mac address use
729 .Fl bssid .
730 .It Cm beacons
731 Mark the cloned interface as depending on hardware support to
732 track received beacons.
733 To have beacons tracked in software use
734 .Fl beacons .
735 For
736 .Cm hostap
737 mode
738 .Fl beacons
739 can also be used to indicate no beacons should
740 be transmitted; this can be useful when creating a WDS configuration but
741 .Cm wds
742 interfaces can only be created as companions to an access point.
743 .El
744 .Pp
745 The following parameters are specific to IEEE 802.11 wireless interfaces
746 cloned with a
747 .Cm create
748 operation:
749 .Bl -tag -width indent
750 .It Cm ampdu
751 Enable sending and receiving AMPDU frames when using 802.11n (default).
752 The 802.11n specification states a compliant station must be capable
753 of receiving AMPDU frames but transmission is optional.
754 Use
755 .Fl ampdu
756 to disable all use of AMPDU with 802.11n.
757 For testing and/or to work around interoperability problems one can use
758 .Cm ampdutx
759 and
760 .Cm ampdurx
761 to control use of AMPDU in one direction.
762 .It Cm ampdudensity Ar density
763 Set the AMPDU density parameter used when operating with 802.11n.
764 This parameter controls the inter-packet gap for AMPDU frames.
765 The sending device normally controls this setting but a receiving station
766 may request wider gaps.
767 Legal values for
768 .Ar density
769 are 0, .25, .5, 1, 2, 4, 8, and 16 (microseconds).
770 A value of
771 .Cm -
772 is treated the same as 0.
773 .It Cm ampdulimit Ar limit
774 Set the limit on packet size for receiving AMPDU frames when operating
775 with 802.11n.
776 Legal values for
777 .Ar limit
778 are 8192, 16384, 32768, and 65536 but one can also specify
779 just the unique prefix: 8, 16, 32, 64.
780 Note the sender may limit the size of AMPDU frames to be less
781 than the maximum specified by the receiving station.
782 .It Cm amsdu
783 Enable sending and receiving AMSDU frames when using 802.11n.
784 By default AMSDU is received but not transmitted.
785 Use
786 .Fl amsdu
787 to disable all use of AMSDU with 802.11n.
788 For testing and/or to work around interoperability problems one can use
789 .Cm amsdutx
790 and
791 .Cm amsdurx
792 to control use of AMSDU in one direction.
793 .It Cm amsdulimit Ar limit
794 Set the limit on packet size for sending and receiving AMSDU frames
795 when operating with 802.11n.
796 Legal values for
797 .Ar limit
798 are 7935 and 3839 (bytes).
799 Note the sender may limit the size of AMSDU frames to be less
800 than the maximum specified by the receiving station.
801 Note also that devices are not required to support the 7935 limit,
802 only 3839 is required by the specification and the larger value
803 may require more memory to be dedicated to support functionality
804 that is rarely used.
805 .It Cm apbridge
806 When operating as an access point, pass packets between
807 wireless clients directly (default).
808 To instead let them pass up through the
809 system and be forwarded using some other mechanism, use
810 .Fl apbridge .
811 Disabling the internal bridging
812 is useful when traffic is to be processed with
813 packet filtering.
814 .It Cm authmode Ar mode
815 Set the desired authentication mode in infrastructure mode.
816 Not all adapters support all modes.
817 The set of
818 valid modes is
819 .Cm none , open , shared
820 (shared key),
821 .Cm 8021x
822 (IEEE 802.1x),
823 and
824 .Cm wpa
825 (IEEE WPA/WPA2/802.11i).
826 The
827 .Cm 8021x
828 and
829 .Cm wpa
830 modes are only useful when using an authentication service
831 (a supplicant for client operation or an authenticator when
832 operating as an access point).
833 Modes are case insensitive.
834 .It Cm bgscan
835 Enable background scanning when operating as a station.
836 Background scanning is a technique whereby a station associated to
837 an access point will temporarily leave the channel to scan for
838 neighboring stations.
839 This allows a station to maintain a cache of nearby access points
840 so that roaming between access points can be done without
841 a lengthy scan operation.
842 Background scanning is done only when a station is not busy and
843 any outbound traffic will cancel a scan operation.
844 Background scanning should never cause packets to be lost though
845 there may be some small latency if outbound traffic interrupts a
846 scan operation.
847 By default background scanning is enabled if the device is capable.
848 To disable background scanning, use
849 .Fl bgscan .
850 Background scanning is controlled by the
851 .Cm bgscanidle
852 and
853 .Cm bgscanintvl
854 parameters.
855 Background scanning must be enabled for roaming; this is an artifact
856 of the current implementation and may not be required in the future.
857 .It Cm bgscanidle Ar idletime
858 Set the minimum time a station must be idle (not transmitting or
859 receiving frames) before a background scan is initiated.
860 The
861 .Ar idletime
862 parameter is specified in milliseconds.
863 By default a station must be idle at least 250 milliseconds before
864 a background scan is initiated.
865 The idle time may not be set to less than 100 milliseconds.
866 .It Cm bgscanintvl Ar interval
867 Set the interval at which background scanning is attempted.
868 The
869 .Ar interval
870 parameter is specified in seconds.
871 By default a background scan is considered every 300 seconds (5 minutes).
872 The
873 .Ar interval
874 may not be set to less than 15 seconds.
875 .It Cm bintval Ar interval
876 Set the interval at which beacon frames are sent when operating in
877 ad-hoc or ap mode.
878 The
879 .Ar interval
880 parameter is specified in TU's (1024 usecs).
881 By default beacon frames are transmitted every 100 TU's.
882 .It Cm bmissthreshold Ar count
883 Set the number of consecutive missed beacons at which the station
884 will attempt to roam (i.e., search for a new access point).
885 The
886 .Ar count
887 parameter must be in the range 1 to 255; though the
888 upper bound may be reduced according to device capabilities.
889 The default threshold is 7 consecutive missed beacons; but
890 this may be overridden by the device driver.
891 Another name for the
892 .Cm bmissthreshold
893 parameter is
894 .Cm bmiss .
895 .It Cm bssid Ar address
896 Specify the MAC address of the access point to use when operating
897 as a station in a BSS network.
898 This overrides any automatic selection done by the system.
899 To disable a previously selected access point, supply
900 .Cm any , none ,
901 or
902 .Cm -
903 for the address.
904 This option is useful when more than one access point uses the same SSID.
905 Another name for the
906 .Cm bssid
907 parameter is
908 .Cm ap .
909 .It Cm burst
910 Enable packet bursting.
911 Packet bursting is a transmission technique whereby the wireless
912 medium is acquired once to send multiple frames and the interframe
913 spacing is reduced.
914 This technique can significantly increase throughput by reducing
915 transmission overhead.
916 Packet bursting is supported by the 802.11e QoS specification
917 and some devices that do not support QoS may still be capable.
918 By default packet bursting is enabled if a device is capable
919 of doing it.
920 To disable packet bursting, use
921 .Fl burst .
922 .It Cm chanlist Ar channels
923 Set the desired channels to use when scanning for access
924 points, neighbors in an IBSS network, or looking for unoccupied
925 channels when operating as an access point.
926 The set of channels is specified as a comma-separated list with
927 each element in the list representing either a single channel number or a range
928 of the form
929 .Dq Li a-b .
930 Channel numbers must be in the range 1 to 255 and be permissible
931 according to the operating characteristics of the device.
932 .It Cm channel Ar number
933 Set a single desired channel.
934 Channels range from 1 to 255, but the exact selection available
935 depends on the region your adaptor was manufactured for.
936 Setting
937 the channel to
938 .Li any ,
939 or
940 .Cm -
941 will clear any desired channel and, if the device is marked up,
942 force a scan for a channel to operate on.
943 Alternatively the frequency, in megahertz, may be specified
944 instead of the channel number.
945 .Pp
946 When there are several ways to use a channel the channel
947 number/frequency may be appended with attributes to clarify.
948 For example, if a device is capable of operating on channel 6
949 with 802.11n and 802.11g then one can specify that g-only use
950 should be used by specifying ``6:g''.
951 Similarly the channel width can be specified by appending it
952 with ``/''; e.g. ``6/40'' specifies a 40MHz wide channel,
953 These attributes can be combined as in: ``6:ht/40''.
954 The full set of flags specified following a `:'' are:
955 .Cm a
956 (802.11a),
957 .Cm b
958 (802.11b),
959 .Cm d
960 (Atheros Dynamic Turbo mode),
961 .Cm g
962 (802.11g),
963 .Cm h
964 or
965 .Cm n
966 (802.11n aka HT),
967 .Cm s
968 (Atheros Static Turbo mode),
969 and
970 .Cm t
971 (Atheros Dynamic Turbo mode, or appended to ``st'' and ``dt'').
972 The full set of channel widths following a '/' are:
973 .Cm 5
974 (5MHz aka quarter-rate channel),
975 .Cm 10
976 (10MHz aka half-rate channel),
977 .Cm 20
978 (20MHz mostly for use in specifying ht20),
979 and
980 .Cm 40
981 (40MHz mostly for use in specifying ht40),
982 In addition,
983 a 40MHz HT channel specification may include the location
984 of the extension channel by appending ``+'' or ``-'' for above and below,
985 respectively; e.g. ``2437:ht/40+'' specifies 40MHz wide HT operation
986 with the center channel at frequency 2437 and the extension channel above.
987 .It Cm country Ar name
988 Set the country code to use in calculating the regulatory constraints
989 for operation.
990 In particular the set of available channels, how the wireless device
991 will operation on the channels, and the maximum transmit power that
992 can be used on a channel are defined by this setting.
993 Country/Region codes are specified as a 2-character abbreviation
994 defined by ISO 3166 or using a longer, but possibly ambiguous, spelling;
995 e.g. "ES" and "Spain".
996 The set of country codes are taken from /etc/regdomain.xml and can also
997 be viewed with the ``list countries'' request.
998 Note that not all devices support changing the country code from a default
999 setting; typically stored in EEPROM.
1000 See also
1001 .Cm regdomain ,
1002 .Cm indoor ,
1003 .Cm outdoor ,
1004 and
1005 .Cm anywhere .
1006 .It Cm dfs
1007 Enable Dynamic Frequency Selection (DFS) as specified in 802.11h.
1008 DFS embodies several facilities including detection of overlapping
1009 radar signals, dynamic transmit power control, and channel selection
1010 according to a least-congested criteria.
1011 DFS support is mandatory for some 5Ghz frequencies in certain
1012 locales (e.g. ETSI).
1013 By default DFS is enabled according to the regulatory definitions
1014 specified in /etc/regdomain.xml and the current country code, regdomain,
1015 and channel.
1016 Note the underlying device (and driver) must support radar detection
1017 for full DFS support to work.
1018 To be fully compliant with the local regulatory agency frequencies that
1019 require DFS should not be used unless it is fully supported.
1020 Use
1021 .Fl dfs
1022 to disable this functionality for testing.
1023 .It Cm dotd
1024 Enable support for the 802.11d specification (default).
1025 When this support is enabled in station mode, beacon frames that advertise
1026 a country code different than the currently configured country code will
1027 cause an event to be dispatched to user applications.
1028 This event can be used by the station to adopt that country code and
1029 operate according to the associated regulatory constraints.
1030 When operating as an access point with 802.11d enabled the beacon and
1031 probe response frames transmitted will advertise the current regulatory
1032 domain settings.
1033 To disable 802.11d use
1034 .Fl dotd .
1035 .It Cm doth
1036 Enable 802.11h support including spectrum management.
1037 When 802.11h is enabled beacon and probe response frames will have
1038 the SpectrumMgt bit set in the capabilities field and
1039 country and power constraint information elements will be present.
1040 802.11h support also includes handling Channel Switch Announcements (CSA)
1041 which are a mechanism to coordinate channel changes by an access point.
1042 By default 802.11h is enabled if the device is capable.
1043 To disable 802.11h use
1044 .Fl doth .
1045 .It Cm deftxkey Ar index
1046 Set the default key to use for transmission.
1047 Typically this is only set when using WEP encryption.
1048 Note that you must set a default transmit key
1049 for the system to know which key to use in encrypting outbound traffic.
1050 The
1051 .Cm weptxkey
1052 is an alias for this request; it is provided for backwards compatibility.
1053 .It Cm dtimperiod Ar period
1054 Set the
1055 DTIM
1056 period for transmitting buffered multicast data frames when
1057 operating in ap mode.
1058 The
1059 .Ar period
1060 specifies the number of beacon intervals between DTIM
1061 and must be in the range 1 to 15.
1062 By default DTIM is 1 (i.e., DTIM occurs at each beacon).
1063 .It Cm dturbo
1064 Enable the use of Atheros Dynamic Turbo mode when communicating with
1065 another Dynamic Turbo-capable station.
1066 Dynamic Turbo mode is an Atheros-specific mechanism by which
1067 stations switch between normal 802.11 operation and a ``boosted''
1068 mode in which a 40MHz wide channel is used for communication.
1069 Stations using Dynamic Turbo mode operate boosted only when the
1070 channel is free of non-dturbo stations; when a non-dturbo station
1071 is identified on the channel all stations will automatically drop
1072 back to normal operation.
1073 By default, Dynamic Turbo mode is not enabled, even if the device is capable.
1074 Note that turbo mode (dynamic or static) is only allowed on some
1075 channels depending on the regulatory constraints; use the
1076 .Cm list chan
1077 command to identify the channels where turbo mode may be used.
1078 To disable Dynamic Turbo mode use
1079 .Fl dturbo .
1080 .It Cm dwds
1081 Enable Dynamic WDS (DWDS) support.
1082 DWDS is a facility by which 4-address traffic can be carried between
1083 stations operating in infrastructure mode.
1084 A station first associates to an access point and authenticates using
1085 normal procedures (e.g. WPA).
1086 Then 4-address frames are passed to carry traffic for stations
1087 operating on either side of the wireless link.
1088 DWDS extends the normal WDS mechanism by leveraging existing security
1089 protocols and eliminating static binding.
1090 .Pp
1091 When DWDS is enabled on an access point 4-address frames received from
1092 an authorized station will generate a ``DWDS discovery'' event to user
1093 applications.
1094 This event should be used to create a WDS interface that is bound
1095 to the remote station (and usually plumbed into a bridge).
1096 Once the WDS interface is up and running 4-address traffic then logically
1097 flows through that interface.
1098 .Pp
1099 When DWDS is enabled on a station, traffic with a destination address
1100 different from the peer station are encapsulated in a 4-address frame
1101 and transmitted to the peer.
1102 All 4-address traffic uses the security information of the stations
1103 (e.g. cryptographic keys).
1104 A station is associated using 802.11n facilities may transport
1105 4-address traffic using these same mechanisms; this depends on available
1106 resources and capabilities of the device.
1107 The DWDS implementation guards against layer 2 routing loops of
1108 multicast traffic.
1109 .It Cm ff
1110 Enable the use of Atheros Fast Frames when communicating with
1111 another Fast Frames-capable station.
1112 Fast Frames are an encapsulation technique by which two 802.3
1113 frames are transmitted in a single 802.11 frame.
1114 This can noticeably improve throughput but requires that the
1115 receiving station understand how to decapsulate the frame.
1116 Fast frame use is negotiated using the Atheros 802.11 vendor-specific
1117 protocol extension so enabling use is safe when communicating with
1118 non-Atheros devices.
1119 By default, use of fast frames is enabled if the device is capable.
1120 To explicitly disable fast frames, use
1121 .Fl ff .
1122 .It Cm fragthreshold Ar length
1123 Set the threshold for which transmitted frames are broken into fragments.
1124 The
1125 .Ar length
1126 argument is the frame size in bytes and must be in the range 256 to 2346.
1127 Setting
1128 .Ar length
1129 to
1130 .Li 2346 ,
1131 .Cm any ,
1132 or
1133 .Cm -
1134 disables transmit fragmentation.
1135 Not all adapters honor the fragmentation threshold.
1136 .It Cm hidessid
1137 When operating as an access point, do not broadcast the SSID
1138 in beacon frames or respond to probe request frames unless
1139 they are directed to the ap (i.e., they include the ap's SSID).
1140 By default, the SSID is included in beacon frames and
1141 undirected probe request frames are answered.
1142 To re-enable the broadcast of the SSID etc., use
1143 .Fl hidessid .
1144 .It Cm ht
1145 Enable use of High Throughput (HT) when using 802.11n (default).
1146 The 802.11n specification includes mechanisms for operation
1147 on 20MHz and 40MHz wide channels using different signalling mechanisms
1148 than specified in 802.11b, 802.11g, and 802.11a.
1149 Stations negotiate use of these facilities, termed HT20 and HT40,
1150 when they associate.
1151 To disable all use of 802.11n use
1152 .Fl ht .
1153 To disable use of HT20 (e.g. to force only HT40 use) use
1154 .Fl ht20 .
1155 To disable use of HT40 use
1156 .Fl ht40 .
1157 .Pp
1158 HT configuration is used to ``auto promote'' operation
1159 when several choices are available.
1160 For example, if a station associates to an 11n-capable access point
1161 it controls whether the station uses legacy operation, HT20, or HT40.
1162 When an 11n-capable device is setup as an access point and
1163 Auto Channel Selection is used to locate a channel to operate on,
1164 HT configuration controls whether legacy, HT20, or HT40 operation is setup
1165 on the selected channel.
1166 If a fixed channel is specified for a station then HT configuration can
1167 be given as part of the channel specification; e.g. 6:ht/20 to setup
1168 HT20 operation on channel 6.
1169 .It Cm htcompat
1170 Enable use of compatibility support for pre-802.11n devices (default).
1171 The 802.11n protocol specification went through several incompatible iterations.
1172 Some vendors implemented 11n support to older specifications that
1173 will not interoperate with a purely 11n-compliant station.
1174 In particular the information elements included in management frames
1175 for old devices are different.
1176 When compatibility support is enabled both standard and compatible data
1177 will be provided.
1178 Stations that associate using the compatibility mechanisms are flagged
1179 in ``list sta''.
1180 To disable compatibility support use
1181 .Fl htcompat .
1182 .It Cm htprotmode Ar technique
1183 For interfaces operating in 802.11n, use the specified
1184 .Ar technique
1185 for protecting HT frames in a mixed legacy/HT network.
1186 The set of valid techniques is
1187 .Cm off ,
1188 and
1189 .Cm rts
1190 (RTS/CTS, default).
1191 Technique names are case insensitive.
1192 .It Cm inact
1193 Enable inactivity processing for stations associated to an
1194 access point (default).
1195 When operating as an access point the 802.11 layer monitors
1196 the activity of each associated station.
1197 When a station is inactive for 5 minutes it will send several
1198 ``probe frames'' to see if the station is still present.
1199 If no response is received then the station is deauthenticated.
1200 Applications that prefer to handle this work can disable this
1201 facility by using
1202 .Fl inact .
1203 .It Cm indoor
1204 Set the location to use in calculating regulatory constraints.
1205 The location is also advertised in beacon and probe response frames
1206 when 802.11d is enabled with
1207 .Cm dotd .
1208 See also
1209 .Cm outdoor ,
1210 .Cm anywhere ,
1211 .Cm country ,
1212 and
1213 .Cm regdomain .
1214 .It Cm list active
1215 Display the list of channels available for use taking into account
1216 any restrictions set with the
1217 .Cm chanlist
1218 directive.
1219 See the description of
1220 .Cm list chan
1221 for more information.
1222 .It Cm list caps
1223 Display the adaptor's capabilities, including the operating
1224 modes supported.
1225 .It Cm list chan
1226 Display the list of channels available for use.
1227 Channels are shown with their IEEE channel number, equivalent
1228 frequency, and usage modes.
1229 Channels identified as
1230 .Ql 11g
1231 are also usable in
1232 .Ql 11b
1233 mode.
1234 Channels identified as
1235 .Ql 11a Turbo
1236 may be used only for Atheros' Static Turbo mode
1237 (specified with
1238 .Cm mediaopt turbo ) .
1239 Channels marked with a
1240 .Ql *
1241 have a regulatory constraint that they be passively scanned.
1242 This means a station is not permitted to transmit on the channel until
1243 it identifies the channel is being used for 802.11 communication;
1244 typically by hearing a beacon frame from an access point operating
1245 on the channel.
1246 .Cm list freq
1247 is another way of requesting this information.
1248 By default a compacted list of channels is displayed; if the
1249 .Fl v
1250 option is specified then all channels are shown.
1251 .It Cm list countries
1252 Display the set of country codes and regulatory domains that can be
1253 used in regulatory configuration.
1254 .It Cm list mac
1255 Display the current MAC Access Control List state.
1256 Each address is prefixed with a character that indicates the
1257 current policy applied to it:
1258 .Ql +
1259 indicates the address is allowed access,
1260 .Ql -
1261 indicates the address is denied access,
1262 .Ql *
1263 indicates the address is present but the current policy open
1264 (so the ACL is not consulted).
1265 .It Cm list mesh
1266 Displays the mesh routing table, used for forwarding packets on a mesh
1267 network.
1268 .It Cm list regdomain
1269 Display the current regulatory settings including the available channels
1270 and transmit power caps.
1271 .It Cm list roam
1272 Display the parameters that govern roaming operation.
1273 .It Cm list txparam
1274 Display the parameters that govern transmit operation.
1275 .It Cm list txpower
1276 Display the transmit power caps for each channel.
1277 .It Cm list scan
1278 Display the access points and/or ad-hoc neighbors
1279 located in the vicinity.
1280 This information may be updated automatically by the adapter
1281 with a
1282 .Cm scan
1283 request or through background scanning.
1284 Depending on the capabilities of the stations the following
1285 flags can be included in the output:
1286 .Bl -tag -width 3n
1287 .It Li A
1288 Authorized.
1289 Indicates that the station is permitted to send/receive data frames.
1290 .It Li E
1291 Extended Rate Phy (ERP).
1292 Indicates that the station is operating in an 802.11g network
1293 using extended transmit rates.
1294 .It Li H
1295 High Throughput (HT).
1296 Indicates that the station is using HT transmit rates.
1297 If a `+' follows immediately after then the station associated
1298 using deprecated mechanisms supported only when
1299 .Cm htcompat
1300 is enabled.
1301 .It Li P
1302 Power Save.
1303 Indicates that the station is operating in power save mode.
1304 .It Li Q
1305 Quality of Service (QoS).
1306 Indicates that the station is using QoS encapsulation for
1307 data frame.
1308 QoS encapsulation is enabled only when WME mode is enabled.
1309 .It Li T
1310 Transitional Security Network (TSN).
1311 Indicates that the station associated using TSN; see also
1312 .Cm tsn
1313 below.
1314 .It Li W
1315 Wi-Fi Protected Setup (WPS).
1316 Indicates that the station associated using WPS.
1317 .El
1318 .Pp
1319 By default interesting information elements captured from the neighboring
1320 stations are displayed at the end of each row.
1321 Possible elements include:
1322 .Cm WME
1323 (station supports WME),
1324 .Cm WPA
1325 (station supports WPA),
1326 .Cm WPS
1327 (station supports WPS),
1328 .Cm RSN
1329 (station supports 802.11i/RSN),
1330 .Cm HTCAP
1331 (station supports 802.11n/HT communication),
1332 .Cm ATH
1333 (station supports Atheros protocol extensions),
1334 .Cm VEN
1335 (station supports unknown vendor-specific extensions).
1336 If the
1337 .Fl v
1338 flag is used all the information elements and their
1339 contents will be shown.
1340 Specifying the
1341 .Fl v
1342 flag also enables display of long SSIDs.
1343 The
1344 .Cm list ap
1345 command is another way of requesting this information.
1346 .It Cm list sta
1347 When operating as an access point display the stations that are
1348 currently associated.
1349 When operating in ad-hoc mode display stations identified as
1350 neighbors in the IBSS.
1351 When operating in mesh mode display stations identified as
1352 neighbors in the MBSS.
1353 When operating in station mode display the access point.
1354 Capabilities advertised by the stations are described under
1355 the
1356 .Cm scan
1357 request.
1358 Depending on the capabilities of the stations the following
1359 flags can be included in the output:
1360 .Bl -tag -width 3n
1361 .It Li A
1362 Authorized.
1363 Indicates that the station is permitted to send/receive data frames.
1364 .It Li E
1365 Extended Rate Phy (ERP).
1366 Indicates that the station is operating in an 802.11g network
1367 using extended transmit rates.
1368 .It Li H
1369 High Throughput (HT).
1370 Indicates that the station is using HT transmit rates.
1371 If a `+' follows immediately after then the station associated
1372 using deprecated mechanisms supported only when
1373 .Cm htcompat
1374 is enabled.
1375 .It Li P
1376 Power Save.
1377 Indicates that the station is operating in power save mode.
1378 .It Li Q
1379 Quality of Service (QoS).
1380 Indicates that the station is using QoS encapsulation for
1381 data frame.
1382 QoS encapsulation is enabled only when WME mode is enabled.
1383 .It Li T
1384 Transitional Security Network (TSN).
1385 Indicates that the station associated using TSN; see also
1386 .Cm tsn
1387 below.
1388 .It Li W
1389 Wi-Fi Protected Setup (WPS).
1390 Indicates that the station associated using WPS.
1391 .El
1392 .Pp
1393 By default information elements received from associated stations
1394 are displayed in a short form; the
1395 .Fl v
1396 flag causes this information to be displayed symbolically.
1397 .It Cm list wme
1398 Display the current channel parameters to use when operating in WME mode.
1399 If the
1400 .Fl v
1401 option is specified then both channel and BSS parameters are displayed
1402 for each AC (first channel, then BSS).
1403 When WME mode is enabled for an adaptor this information will be
1404 displayed with the regular status; this command is mostly useful
1405 for examining parameters when WME mode is disabled.
1406 See the description of the
1407 .Cm wme
1408 directive for information on the various parameters.
1409 .It Cm lscan
1410 A variant of
1411 .Cm scan
1412 (see below) that displays long SSIDs.
1413 .It Cm maxretry Ar count
1414 Set the maximum number of tries to use in sending unicast frames.
1415 The default setting is 6 but drivers may override this with a value
1416 they choose.
1417 .It Cm mcastrate Ar rate
1418 Set the rate for transmitting multicast/broadcast frames.
1419 Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s.
1420 This rate should be valid for the current operating conditions;
1421 if an invalid rate is specified drivers are free to choose an
1422 appropriate rate.
1423 .It Cm mgtrate Ar rate
1424 Set the rate for transmitting management and/or control frames.
1425 Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s.
1426 .It Cm outdoor
1427 Set the location to use in calculating regulatory constraints.
1428 The location is also advertised in beacon and probe response frames
1429 when 802.11d is enabled with
1430 .Cm dotd .
1431 See also
1432 .Cm anywhere ,
1433 .Cm country ,
1434 .Cm indoor ,
1435 and
1436 .Cm regdomain .
1437 .It Cm powersave
1438 Enable powersave operation.
1439 When operating as a client, the station will conserve power by
1440 periodically turning off the radio and listening for
1441 messages from the access point telling it there are packets waiting.
1442 The station must then retrieve the packets.
1443 Not all devices support power save operation as a client.
1444 The 802.11 specification requires that all access points support
1445 power save but some drivers do not.
1446 Use
1447 .Fl powersave
1448 to disable powersave operation when operating as a client.
1449 .It Cm powersavemode Ar mode
1450 Set powersave mode.
1451 The set of valid modes is
1452 .Cm off
1453 (same as
1454 .Fl powersave ) ,
1455 .Cm on
1456 (same as
1457 .Cm powersave ) ,
1458 and
1459 .Cm cam
1460 (same as
1461 .Cm powersave ) .
1462 .It Cm powersavesleep Ar sleep
1463 Set the desired max powersave sleep time in TU's (1024 usecs).
1464 By default the max powersave sleep time is 100 TU's.
1465 .It Cm protmode Ar technique
1466 For interfaces operating in 802.11g, use the specified
1467 .Ar technique
1468 for protecting OFDM frames in a mixed 11b/11g network.
1469 The set of valid techniques is
1470 .Cm off , cts
1471 (CTS to self),
1472 and
1473 .Cm rtscts
1474 (RTS/CTS).
1475 Technique names are case insensitive.
1476 Not all devices support
1477 .Cm cts
1478 as a protection technique.
1479 .It Cm pureg
1480 When operating as an access point in 802.11g mode allow only
1481 11g-capable stations to associate (11b-only stations are not
1482 permitted to associate).
1483 To allow both 11g and 11b-only stations to associate, use
1484 .Fl pureg .
1485 .It Cm puren
1486 When operating as an access point in 802.11n mode allow only
1487 HT-capable stations to associate (legacy stations are not
1488 permitted to associate).
1489 To allow both HT and legacy stations to associate, use
1490 .Fl puren .
1491 .It Cm regdomain Ar sku
1492 Set the regulatory domain to use in calculating the regulatory constraints
1493 for operation.
1494 In particular the set of available channels, how the wireless device
1495 will operation on the channels, and the maximum transmit power that
1496 can be used on a channel are defined by this setting.
1497 Regdomain codes (SKU's) are taken from /etc/regdomain.xml and can also
1498 be viewed with the ``list countries'' request.
1499 Note that not all devices support changing the regdomain from a default
1500 setting; typically stored in EEPROM.
1501 See also
1502 .Cm country ,
1503 .Cm indoor ,
1504 .Cm outdoor ,
1505 and
1506 .Cm anywhere .
1507 .It Cm rifs
1508 Enable use of Reduced InterFrame Spacing (RIFS) when operating in 802.11n
1509 on an HT channel.
1510 Note that RIFS must be supported by both the station and access point
1511 for it to be used.
1512 To disable RIFS use
1513 .Fl rifs .
1514 .It Cm roam:rate Ar rate
1515 Set the threshold for controlling roaming when operating in a BSS.
1516 The
1517 .Ar rate
1518 parameter specifies the transmit rate in megabits
1519 at which roaming should be considered.
1520 If the current transmit rate drops below this setting and background scanning
1521 is enabled, then the system will check if a more desirable access point is
1522 available and switch over to it.
1523 The current scan cache contents are used if they are considered
1524 valid according to the
1525 .Cm scanvalid
1526 parameter; otherwise a background scan operation is triggered before
1527 any selection occurs.
1528 Each channel type has a separate rate threshold; the default values are:
1529 12 Mb/s (11a), 2 Mb/s (11b), 2 Mb/s (11g), MCS 1 (11na, 11ng).
1530 .It Cm roam:rssi Ar rssi
1531 Set the threshold for controlling roaming when operating in a BSS.
1532 The
1533 .Ar rssi
1534 parameter specifies the receive signal strength in dBm units
1535 at which roaming should be considered.
1536 If the current rssi drops below this setting and background scanning
1537 is enabled, then the system will check if a more desirable access point is
1538 available and switch over to it.
1539 The current scan cache contents are used if they are considered
1540 valid according to the
1541 .Cm scanvalid
1542 parameter; otherwise a background scan operation is triggered before
1543 any selection occurs.
1544 Each channel type has a separate rssi threshold; the default values are
1545 all 7 dBm.
1546 .It Cm roaming Ar mode
1547 When operating as a station, control how the system will
1548 behave when communication with the current access point
1549 is broken.
1550 The
1551 .Ar mode
1552 argument may be one of
1553 .Cm device
1554 (leave it to the hardware device to decide),
1555 .Cm auto
1556 (handle either in the device or the operating system\[em]as appropriate),
1557 .Cm manual
1558 (do nothing until explicitly instructed).
1559 By default, the device is left to handle this if it is
1560 capable; otherwise, the operating system will automatically
1561 attempt to reestablish communication.
1562 Manual mode is used by applications such as
1563 .Xr wpa_supplicant 8
1564 that want to control the selection of an access point.
1565 .It Cm rtsthreshold Ar length
1566 Set the threshold for which
1567 transmitted frames are preceded by transmission of an
1568 RTS
1569 control frame.
1570 The
1571 .Ar length
1572 argument
1573 is the frame size in bytes and must be in the range 1 to 2346.
1574 Setting
1575 .Ar length
1576 to
1577 .Li 2346 ,
1578 .Cm any ,
1579 or
1580 .Cm -
1581 disables transmission of RTS frames.
1582 Not all adapters support setting the RTS threshold.
1583 .It Cm scan
1584 Initiate a scan of neighboring stations, wait for it to complete, and
1585 display all stations found.
1586 Only the super-user can initiate a scan.
1587 See
1588 .Cm list scan
1589 for information on the display.
1590 By default a background scan is done; otherwise a foreground
1591 scan is done and the station may roam to a different access point.
1592 The
1593 .Cm list scan
1594 request can be used to show recent scan results without
1595 initiating a new scan.
1596 .It Cm scanvalid Ar threshold
1597 Set the maximum time the scan cache contents are considered valid;
1598 i.e. will be used without first triggering a scan operation to
1599 refresh the data.
1600 The
1601 .Ar threshold
1602 parameter is specified in seconds and defaults to 60 seconds.
1603 The minimum setting for
1604 .Ar threshold
1605 is 10 seconds.
1606 One should take care setting this threshold; if it is set too low
1607 then attempts to roam to another access point may trigger unnecessary
1608 background scan operations.
1609 .It Cm shortgi
1610 Enable use of Short Guard Interval when operating in 802.11n
1611 on an HT channel.
1612 NB: this currently enables Short GI on both HT40 and HT20 channels.
1613 To disable Short GI use
1614 .Fl shortgi .
1615 .It Cm smps
1616 Enable use of Static Spatial Multiplexing Power Save (SMPS)
1617 when operating in 802.11n.
1618 A station operating with Static SMPS maintains only a single
1619 receive chain active (this can significantly reduce power consumption).
1620 To disable SMPS use
1621 .Fl smps .
1622 .It Cm smpsdyn
1623 Enable use of Dynamic Spatial Multiplexing Power Save (SMPS)
1624 when operating in 802.11n.
1625 A station operating with Dynamic SMPS maintains only a single
1626 receive chain active but switches to multiple receive chains when it
1627 receives an RTS frame (this can significantly reduce power consumption).
1628 Note that stations cannot distinguish between RTS/CTS intended to
1629 enable multiple receive chains and those used for other purposes.
1630 To disable SMPS use
1631 .Fl smps .
1632 .It Cm ssid Ar ssid
1633 Set the desired Service Set Identifier (aka network name).
1634 The SSID is a string up to 32 characters
1635 in length and may be specified as either a normal string or in
1636 hexadecimal when preceded by
1637 .Ql 0x .
1638 Additionally, the SSID may be cleared by setting it to
1639 .Ql - .
1640 .It Cm tdmaslot Ar slot
1641 When operating with TDMA, use the specified
1642 .Ar slot
1643 configuration.
1644 The
1645 .Ar slot
1646 is a number between 0 and the maximum number of slots in the BSS.
1647 Note that a station configured as slot 0 is a master and
1648 will broadcast beacon frames advertising the BSS;
1649 stations configured to use other slots will always
1650 scan to locate a master before they ever transmit.
1651 By default
1652 .Cm tdmaslot
1653 is set to 1.
1654 .It Cm tdmaslotcnt Ar cnt
1655 When operating with TDMA, setup a BSS with
1656 .Ar cnt
1657 slots.
1658 The slot count may be at most 8.
1659 The current implementation is only tested with two stations
1660 (i.e. point to point applications).
1661 This setting is only meaningful when a station is configured as slot 0;
1662 other stations adopt this setting from the BSS they join.
1663 By default
1664 .Cm tdmaslotcnt
1665 is set to 2.
1666 .It Cm tdmaslotlen Ar len
1667 When operating with TDMA, setup a BSS such that each station has a slot
1668 .Ar len
1669 microseconds long.
1670 The slot length must be at least 150 microseconds (1/8 TU)
1671 and no more than 65 milliseconds.
1672 Note that setting too small a slot length may result in poor channel
1673 bandwidth utilization due to factors such as timer granularity and
1674 guard time.
1675 This setting is only meaningful when a station is configured as slot 0;
1676 other stations adopt this setting from the BSS they join.
1677 By default
1678 .Cm tdmaslotlen
1679 is set to 10 milliseconds.
1680 .It Cm tdmabintval Ar intval
1681 When operating with TDMA, setup a BSS such that beacons are transmitted every
1682 .Ar intval
1683 superframes to synchronize the TDMA slot timing.
1684 A superframe is defined as the number of slots times the slot length; e.g.
1685 a BSS with two slots of 10 milliseconds has a 20 millisecond superframe.
1686 The beacon interval may not be zero.
1687 A lower setting of
1688 .Cm tdmabintval
1689 causes the timers to be resynchronized more often; this can be help if
1690 significant timer drift is observed.
1691 By default
1692 .Cm tdmabintval
1693 is set to 5.
1694 .It Cm tsn
1695 When operating as an access point with WPA/802.11i allow legacy
1696 stations to associate using static key WEP and open authentication.
1697 To disallow legacy station use of WEP, use
1698 .Fl tsn .
1699 .It Cm txpower Ar power
1700 Set the power used to transmit frames.
1701 The
1702 .Ar power
1703 argument is specified in .5 dBm units.
1704 Out of range values are truncated.
1705 Typically only a few discreet power settings are available and
1706 the driver will use the setting closest to the specified value.
1707 Not all adapters support changing the transmit power.
1708 .It Cm ucastrate Ar rate
1709 Set a fixed rate for transmitting unicast frames.
1710 Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s.
1711 This rate should be valid for the current operating conditions;
1712 if an invalid rate is specified drivers are free to choose an
1713 appropriate rate.
1714 .It Cm wepmode Ar mode
1715 Set the desired WEP mode.
1716 Not all adapters support all modes.
1717 The set of valid modes is
1718 .Cm off , on ,
1719 and
1720 .Cm mixed .
1721 The
1722 .Cm mixed
1723 mode explicitly tells the adaptor to allow association with access
1724 points which allow both encrypted and unencrypted traffic.
1725 On these adapters,
1726 .Cm on
1727 means that the access point must only allow encrypted connections.
1728 On other adapters,
1729 .Cm on
1730 is generally another name for
1731 .Cm mixed .
1732 Modes are case insensitive.
1733 .It Cm weptxkey Ar index
1734 Set the WEP key to be used for transmission.
1735 This is the same as setting the default transmission key with
1736 .Cm deftxkey .
1737 .It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key
1738 Set the selected WEP key.
1739 If an
1740 .Ar index
1741 is not given, key 1 is set.
1742 A WEP key will be either 5 or 13
1743 characters (40 or 104 bits) depending on the local network and the
1744 capabilities of the adaptor.
1745 It may be specified either as a plain
1746 string or as a string of hexadecimal digits preceded by
1747 .Ql 0x .
1748 For maximum portability, hex keys are recommended;
1749 the mapping of text keys to WEP encryption is usually driver-specific.
1750 In particular, the
1751 .Tn Windows
1752 drivers do this mapping differently to
1753 .Fx .
1754 A key may be cleared by setting it to
1755 .Ql - .
1756 If WEP is supported then there are at least four keys.
1757 Some adapters support more than four keys.
1758 If that is the case, then the first four keys
1759 (1-4) will be the standard temporary keys and any others will be adaptor
1760 specific keys such as permanent keys stored in NVRAM.
1761 .Pp
1762 Note that you must set a default transmit key with
1763 .Cm deftxkey
1764 for the system to know which key to use in encrypting outbound traffic.
1765 .It Cm wme
1766 Enable Wireless Multimedia Extensions (WME) support, if available,
1767 for the specified interface.
1768 WME is a subset of the IEEE 802.11e standard to support the
1769 efficient communication of realtime and multimedia data.
1770 To disable WME support, use
1771 .Fl wme .
1772 Another name for this parameter is
1773 .Cm wmm .
1774 .Pp
1775 The following parameters are meaningful only when WME support is in use.
1776 Parameters are specified per-AC (Access Category) and
1777 split into those that are used by a station when acting
1778 as an access point and those for client stations in the BSS.
1779 The latter are received from the access point and may not be changed
1780 (at the station).
1781 The following Access Categories are recognized:
1782 .Pp
1783 .Bl -tag -width ".Cm AC_BK" -compact
1784 .It Cm AC_BE
1785 (or
1786 .Cm BE )
1787 best effort delivery,
1788 .It Cm AC_BK
1789 (or
1790 .Cm BK )
1791 background traffic,
1792 .It Cm AC_VI
1793 (or
1794 .Cm VI )
1795 video traffic,
1796 .It Cm AC_VO
1797 (or
1798 .Cm VO )
1799 voice traffic.
1800 .El
1801 .Pp
1802 AC parameters are case-insensitive.
1803 Traffic classification is done in the operating system using the
1804 vlan priority associated with data frames or the
1805 ToS (Type of Service) indication in IP-encapsulated frames.
1806 If neither information is present, traffic is assigned to the
1807 Best Effort (BE) category.
1808 .Bl -tag -width indent
1809 .It Cm ack Ar ac
1810 Set the ACK policy for QoS transmissions by the local station;
1811 this controls whether or not data frames transmitted by a station
1812 require an ACK response from the receiving station.
1813 To disable waiting for an ACK use
1814 .Fl ack .
1815 This parameter is applied only to the local station.
1816 .It Cm acm Ar ac
1817 Enable the Admission Control Mandatory (ACM) mechanism
1818 for transmissions by the local station.
1819 To disable the ACM use
1820 .Fl acm .
1821 On stations in a BSS this parameter is read-only and indicates
1822 the setting received from the access point.
1823 NB: ACM is not supported right now.
1824 .It Cm aifs Ar ac Ar count
1825 Set the Arbitration Inter Frame Spacing (AIFS)
1826 channel access parameter to use for transmissions
1827 by the local station.
1828 On stations in a BSS this parameter is read-only and indicates
1829 the setting received from the access point.
1830 .It Cm cwmin Ar ac Ar count
1831 Set the CWmin channel access parameter to use for transmissions
1832 by the local station.
1833 On stations in a BSS this parameter is read-only and indicates
1834 the setting received from the access point.
1835 .It Cm cwmax Ar ac Ar count
1836 Set the CWmax channel access parameter to use for transmissions
1837 by the local station.
1838 On stations in a BSS this parameter is read-only and indicates
1839 the setting received from the access point.
1840 .It Cm txoplimit Ar ac Ar limit
1841 Set the Transmission Opportunity Limit channel access parameter
1842 to use for transmissions by the local station.
1843 This parameter defines an interval of time when a WME station
1844 has the right to initiate transmissions onto the wireless medium.
1845 On stations in a BSS this parameter is read-only and indicates
1846 the setting received from the access point.
1847 .It Cm bss:aifs Ar ac Ar count
1848 Set the AIFS channel access parameter to send to stations in a BSS.
1849 This parameter is meaningful only when operating in ap mode.
1850 .It Cm bss:cwmin Ar ac Ar count
1851 Set the CWmin channel access parameter to send to stations in a BSS.
1852 This parameter is meaningful only when operating in ap mode.
1853 .It Cm bss:cwmax Ar ac Ar count
1854 Set the CWmax channel access parameter to send to stations in a BSS.
1855 This parameter is meaningful only when operating in ap mode.
1856 .It Cm bss:txoplimit Ar ac Ar limit
1857 Set the TxOpLimit channel access parameter to send to stations in a BSS.
1858 This parameter is meaningful only when operating in ap mode.
1859 .El
1860 .It Cm wps
1861 Enable Wireless Privacy Subscriber support.
1862 Note that WPS support requires a WPS-capable supplicant.
1863 To disable this function use
1864 .Fl wps .
1865 .El
1866 .Pp
1867 The following parameters support an optional access control list
1868 feature available with some adapters when operating in ap mode; see
1869 .Xr wlan_acl 4 .
1870 This facility allows an access point to accept/deny association
1871 requests based on the MAC address of the station.
1872 Note that this feature does not significantly enhance security
1873 as MAC address spoofing is easy to do.
1874 .Bl -tag -width indent
1875 .It Cm mac:add Ar address
1876 Add the specified MAC address to the database.
1877 Depending on the policy setting association requests from the
1878 specified station will be allowed or denied.
1879 .It Cm mac:allow
1880 Set the ACL policy to permit association only by
1881 stations registered in the database.
1882 .It Cm mac:del Ar address
1883 Delete the specified MAC address from the database.
1884 .It Cm mac:deny
1885 Set the ACL policy to deny association only by
1886 stations registered in the database.
1887 .It Cm mac:kick Ar address
1888 Force the specified station to be deauthenticated.
1889 This typically is done to block a station after updating the
1890 address database.
1891 .It Cm mac:open
1892 Set the ACL policy to allow all stations to associate.
1893 .It Cm mac:flush
1894 Delete all entries in the database.
1895 .It Cm mac:radius
1896 Set the ACL policy to permit association only by
1897 stations approved by a RADIUS server.
1898 Note that this feature requires the
1899 .Xr hostapd 8
1900 program be configured to do the right thing
1901 as it handles the RADIUS processing
1902 (and marks stations as authorized).
1903 .El
1904 .Pp
1905 The following parameters are related to a wireless interface operating in mesh
1906 mode:
1907 .Bl -tag -width indent
1908 .It Cm meshid Ar meshid
1909 Set the desired Mesh Identifier.
1910 The Mesh ID is a string up to 32 characters in length.
1911 A mesh interface must have a Mesh Identifier specified
1912 to reach an operational state.
1913 .It Cm meshttl Ar ttl
1914 Set the desired ``time to live'' for mesh forwarded packets;
1915 this is the number of hops a packet may be forwarded before
1916 it is discarded.
1917 The default setting for
1918 .Cm meshttl
1919 is 31.
1920 .It Cm meshpeering
1921 Enable or disable peering with neighbor mesh stations.
1922 Stations must peer before any data packets can be exchanged.
1923 By default
1924 .Cm meshpeering
1925 is enabled.
1926 .It Cm meshforward
1927 Enable or disable forwarding packets by a mesh interface.
1928 By default
1929 .Cm meshforward
1930 is enabled.
1931 .It Cm meshmetric Ar protocol
1932 Set the specified
1933 .Ar protocol
1934 as the link metric protocol used on a mesh network.
1935 The default protocol is called
1936 .Ar AIRTIME .
1937 The mesh interface will restart after changing this setting.
1938 .It Cm meshpath Ar protocol
1939 Set the specified
1940 .Ar protocol
1941 as the path selection protocol used on a mesh network.
1942 The only available protocol at the moment is called
1943 .Ar HWMP
1944 (Hybrid Wireless Mesh Protocol).
1945 The mesh interface will restart after changing this setting.
1946 .It Cm hwmprootmode Ar mode
1947 Stations on a mesh network can operate as ``root nodes.''
1948 Root nodes try to find paths to all mesh nodes and advertise themselves
1949 regularly.
1950 When there is a root mesh node on a network, other mesh nodes can setup
1951 paths between themselves faster because they can use the root node
1952 to find the destination.
1953 This path may not be the best, but on-demand
1954 routing will eventually find the best path.
1955 The following modes are recognized:
1956 .Pp
1957 .Bl -tag -width ".Cm PROACTIVE" -compact
1958 .It Cm DISABLED
1959 Disable root mode.
1960 .It Cm NORMAL
1961 Send broadcast path requests every two seconds.
1962 Nodes on the mesh without a path to this root mesh station with try to
1963 discover a path to us.
1964 .It Cm PROACTIVE
1965 Send broadcast path requests every two seconds and every node must reply
1966 with a path reply even if it already has a path to this root mesh station,
1967 .It Cm RANN
1968 Send broadcast root announcement (RANN) frames.
1969 Nodes on the mesh without a path to this root mesh station with try to
1970 discover a path to us.
1971 .El
1972 By default
1973 .Cm hwmprootmode
1974 is set to
1975 .Ar DISABLED .
1976 .It Cm hwmpmaxhops Ar cnt
1977 Set the maximum number of hops allowed in an HMWP path to
1978 .Ar cnt .
1979 The default setting for
1980 .Cm hwmpmaxhops
1981 is 31.
1982 .El
1983 .Pp
1984 The following parameters are for compatibility with other systems:
1985 .Bl -tag -width indent
1986 .It Cm nwid Ar ssid
1987 Another name for the
1988 .Cm ssid
1989 parameter.
1990 Included for
1991 .Nx
1992 compatibility.
1993 .It Cm stationname Ar name
1994 Set the name of this station.
1995 The station name is not part of the IEEE 802.11
1996 protocol though some interfaces support it.
1997 As such it only
1998 seems to be meaningful to identical or virtually identical equipment.
1999 Setting the station name is identical in syntax to setting the SSID.
2000 One can also use
2001 .Cm station
2002 for
2003 .Bsx
2004 compatibility.
2005 .It Cm wep
2006 Another way of saying
2007 .Cm wepmode on .
2008 Included for
2009 .Bsx
2010 compatibility.
2011 .It Fl wep
2012 Another way of saying
2013 .Cm wepmode off .
2014 Included for
2015 .Bsx
2016 compatibility.
2017 .It Cm nwkey key
2018 Another way of saying:
2019 .Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" .
2020 Included for
2021 .Nx
2022 compatibility.
2023 .It Cm nwkey Xo
2024 .Sm off
2025 .Ar n : k1 , k2 , k3 , k4
2026 .Sm on
2027 .Xc
2028 Another way of saying
2029 .Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" .
2030 Included for
2031 .Nx
2032 compatibility.
2033 .It Fl nwkey
2034 Another way of saying
2035 .Cm wepmode off .
2036 Included for
2037 .Nx
2038 compatibility.
2039 .El
2040 .Pp
2041 The following parameters are specific to bridge interfaces:
2042 .Bl -tag -width indent
2043 .It Cm addm Ar interface
2044 Add the interface named by
2045 .Ar interface
2046 as a member of the bridge.
2047 The interface is put into promiscuous mode
2048 so that it can receive every packet sent on the network.
2049 .It Cm deletem Ar interface
2050 Remove the interface named by
2051 .Ar interface
2052 from the bridge.
2053 Promiscuous mode is disabled on the interface when
2054 it is removed from the bridge.
2055 .It Cm maxaddr Ar size
2056 Set the size of the bridge address cache to
2057 .Ar size .
2058 The default is 100 entries.
2059 .It Cm timeout Ar seconds
2060 Set the timeout of address cache entries to
2061 .Ar seconds
2062 seconds.
2063 If
2064 .Ar seconds
2065 is zero, then address cache entries will not be expired.
2066 The default is 1200 seconds.
2067 .It Cm addr
2068 Display the addresses that have been learned by the bridge.
2069 .It Cm static Ar interface-name Ar address
2070 Add a static entry into the address cache pointing to
2071 .Ar interface-name .
2072 Static entries are never aged out of the cache or re-placed, even if the
2073 address is seen on a different interface.
2074 .It Cm deladdr Ar address
2075 Delete
2076 .Ar address
2077 from the address cache.
2078 .It Cm flush
2079 Delete all dynamically-learned addresses from the address cache.
2080 .It Cm flushall
2081 Delete all addresses, including static addresses, from the address cache.
2082 .It Cm discover Ar interface
2083 Mark an interface as a
2084 .Dq discovering
2085 interface.
2086 When the bridge has no address cache entry
2087 (either dynamic or static)
2088 for the destination address of a packet,
2089 the bridge will forward the packet to all
2090 member interfaces marked as
2091 .Dq discovering .
2092 This is the default for all interfaces added to a bridge.
2093 .It Fl discover Ar interface
2094 Clear the
2095 .Dq discovering
2096 attribute on a member interface.
2097 For packets without the
2098 .Dq discovering
2099 attribute, the only packets forwarded on the interface are broadcast
2100 or multicast packets and packets for which the destination address
2101 is known to be on the interface's segment.
2102 .It Cm learn Ar interface
2103 Mark an interface as a
2104 .Dq learning
2105 interface.
2106 When a packet arrives on such an interface, the source
2107 address of the packet is entered into the address cache as being a
2108 destination address on the interface's segment.
2109 This is the default for all interfaces added to a bridge.
2110 .It Fl learn Ar interface
2111 Clear the
2112 .Dq learning
2113 attribute on a member interface.
2114 .It Cm span Ar interface
2115 Add the interface named by
2116 .Ar interface
2117 as a span port on the bridge.
2118 Span ports transmit a copy of every frame received by the bridge.
2119 This is most useful for snooping a bridged network passively on
2120 another host connected to one of the span ports of the bridge.
2121 .It Fl span Ar interface
2122 Delete the interface named by
2123 .Ar interface
2124 from the list of span ports of the bridge.
2125 .It Cm stp Ar interface
2126 Enable Spanning Tree protocol on
2127 .Ar interface .
2128 The
2129 .Xr bridge 4
2130 driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
2131 Spanning Tree is used to detect and remove loops in a network topology.
2132 .It Fl stp Ar interface
2133 Disable Spanning Tree protocol on
2134 .Ar interface .
2135 This is the default for all interfaces added to a bridge.
2136 .It Cm maxage Ar seconds
2137 Set the time that a Spanning Tree protocol configuration is valid.
2138 The default is 20 seconds.
2139 The minimum is 1 second and the maximum is 255 seconds.
2140 .It Cm fwddelay Ar seconds
2141 Set the time that must pass before an interface begins forwarding
2142 packets when Spanning Tree is enabled.
2143 The default is 15 seconds.
2144 The minimum is 1 second and the maximum is 255 seconds.
2145 .It Cm hellotime Ar seconds
2146 Set the time between broadcasting of Spanning Tree protocol
2147 configuration messages.
2148 The default is 2 seconds.
2149 The minimum is 1 second and the maximum is 255 seconds.
2150 .It Cm priority Ar value
2151 Set the bridge priority for Spanning Tree.
2152 The default is 32768.
2153 The minimum is 0 and the maximum is 65536.
2154 .It Cm ifpriority Ar interface Ar value
2155 Set the Spanning Tree priority of
2156 .Ar interface
2157 to
2158 .Ar value .
2159 The default is 128.
2160 The minimum is 0 and the maximum is 255.
2161 .Pp
2162 The priority is used to select which interface out of all
2163 forwarding and bonded interfaces with the same MAC
2164 to output a packet on whe
2165 .Cm link2
2166 mode is not being used.
2167 Note that interfaces in the 'blocking' state do not participate
2168 in the priority selection.
2169 If the priorities are the same on a non-bonded member, the
2170 designated member will be used.
2171 .It Cm ifpathcost Ar interface Ar value
2172 Set the Spanning Tree path cost of
2173 .Ar interface
2174 to
2175 .Ar value .
2176 The default is 55.
2177 The minimum is 0 and the maximum is 65535.
2178 .Pp
2179 The path cost is added to both incoming and outgoing packets on the
2180 member, lower values will make the member more valuable.
2181 .It Cm ifbondweight Ar interface Ar value
2182 Set the number of packets to output on a bonded member before
2183 round-robining to the next member.
2184 The default is 1.
2185 Larger values or different values for each member can be used
2186 if bursting would be beneficial or if the outgoing bandwidth
2187 on each of the members is asymmetric.
2188 For example, one specify a value of 6 on tap0 and 4 on tap1
2189 for a 6:4 ratio.
2190 Remember that this also controls packet bursting.
2191 .It Cm link0
2192 The link0 option enables transparent bridging mode.
2193 The bridge will make every effort to retain the Ethernet header
2194 when forwarding packets between interfaces, making the bridging
2195 function work more like a hardware bridge device.
2196 .It Cm link1
2197 The link1 option enables keepalive transmission and automatically
2198 places a member into a special blocked mode if no keepalive reception
2199 occurs.
2200 If either sides of the link uses this option then both sides must use
2201 this option.
2202 This option is impemented by sending CFG updates on the hello interval
2203 to the remote.
2204 The link is considered lost after 10 intervals (typically 20 seconds).
2205 .It Cm link2
2206 The link2 option enables channel bonding (see also ifbondweight).
2207 All member interfaces with the same mac address are considered to
2208 be in a bonding group.
2209 When something like
2210 .Xr tap 4
2211 is used, you can manually control or copy the mac to create bonding groups.
2212 When interface bonding is enabled normally blocked interfaces belonging
2213 to the same bonding group as an active forwarding interface will be
2214 changed to the bonding state.
2215 Both sides of link the member represents must operate in bonding mode
2216 for this to work, otherwise the remote end may decide to throw away
2217 half your packets.
2218 .El
2219 .Pp
2220 The following parameters are specific to IP tunnel interfaces,
2221 .Xr gif 4 :
2222 .Bl -tag -width indent
2223 .It Cm tunnel Ar src_addr dest_addr
2224 Configure the physical source and destination address for IP tunnel
2225 interfaces.
2226 The arguments
2227 .Ar src_addr
2228 and
2229 .Ar dest_addr
2230 are interpreted as the outer source/destination for the encapsulating
2231 IPv4/IPv6 header.
2232 .It Fl tunnel
2233 Unconfigure the physical source and destination address for IP tunnel
2234 interfaces previously configured with
2235 .Cm tunnel .
2236 .It Cm deletetunnel
2237 Another name for the
2238 .Fl tunnel
2239 parameter.
2240 .El
2241 .Pp
2242 The following parameters are specific to
2243 .Xr vlan 4
2244 interfaces:
2245 .Bl -tag -width indent
2246 .It Cm vlan Ar vlan_tag
2247 Set the VLAN tag value to
2248 .Ar vlan_tag .
2249 This value is a 16-bit number which is used to create an 802.1Q
2250 VLAN header for packets sent from the
2251 .Xr vlan 4
2252 interface.
2253 Note that
2254 .Cm vlan
2255 and
2256 .Cm vlandev
2257 must both be set at the same time.
2258 .It Cm vlandev Ar iface
2259 Associate the physical interface
2260 .Ar iface
2261 with a
2262 .Xr vlan 4
2263 interface.
2264 Packets transmitted through the
2265 .Xr vlan 4
2266 interface will be
2267 diverted to the specified physical interface
2268 .Ar iface
2269 with 802.1Q VLAN encapsulation.
2270 Packets with 802.1Q encapsulation received
2271 by the parent interface with the correct VLAN tag will be diverted to
2272 the associated
2273 .Xr vlan 4
2274 pseudo-interface.
2275 The
2276 .Xr vlan 4
2277 interface is assigned a
2278 copy of the parent interface's flags and the parent's Ethernet address.
2279 The
2280 .Cm vlandev
2281 and
2282 .Cm vlan
2283 must both be set at the same time.
2284 If the
2285 .Xr vlan 4
2286 interface already has
2287 a physical interface associated with it, this command will fail.
2288 To
2289 change the association to another physical interface, the existing
2290 association must be cleared first.
2291 .Pp
2292 Note: if the hardware tagging capability
2293 is set on the parent interface, the
2294 .Xr vlan 4
2295 pseudo
2296 interface's behavior changes:
2297 the
2298 .Xr vlan 4
2299 interface recognizes that the
2300 parent interface supports insertion and extraction of VLAN tags on its
2301 own (usually in firmware) and that it should pass packets to and from
2302 the parent unaltered.
2303 .It Fl vlandev Op Ar iface
2304 If the driver is a
2305 .Xr vlan 4
2306 pseudo device, disassociate the parent interface from it.
2307 This breaks the link between the
2308 .Xr vlan 4
2309 interface and its parent,
2310 clears its VLAN tag, flags and its link address and shuts the interface down.
2311 The
2312 .Ar iface
2313 argument is useless and hence deprecated.
2314 .El
2315 .Pp
2316 The following parameters are specific to
2317 .Xr carp 4
2318 interfaces:
2319 .Bl -tag -width indent
2320 .It Cm advbase Ar seconds
2321 Specifies the base of the advertisement interval in seconds.
2322 The acceptable values are 1 to 255.
2323 The default value is 1.
2324 .\" The default value is
2325 .\" .Dv CARP_DFLTINTV .
2326 .It Cm advskew Ar interval
2327 Specifies the skew to add to the base advertisement interval to
2328 make one host advertise slower than another host.
2329 It is specified in 1/256 of seconds.
2330 The acceptable values are 1 to 254.
2331 The default value is 0.
2332 .It Cm pass Ar phrase
2333 Set the authentication key to
2334 .Ar phrase .
2335 .It Cm vhid Ar n
2336 Set the virtual host ID.
2337 This is a required setting.
2338 Acceptable values are 1 to 255.
2339 .El
2340 .Pp
2341 The
2342 .Nm
2343 utility displays the current configuration for a network interface
2344 when no optional parameters are supplied.
2345 If a protocol family is specified,
2346 .Nm
2347 will report only the details specific to that protocol family.
2348 .Pp
2349 If the
2350 .Fl m
2351 flag is passed before an interface name,
2352 .Nm
2353 will display the capability list,
2354 the maximum amount of data
2355 that TCP segmentation offloading is allowed to aggregate and
2356 all of the supported media for the specified interface.
2357 If
2358 .Fl L
2359 flag is supplied, address lifetime is displayed for IPv6 addresses,
2360 as time offset string.
2361 .Pp
2362 Optionally, the
2363 .Fl a
2364 flag may be used instead of an interface name.
2365 This flag instructs
2366 .Nm
2367 to display information about all interfaces in the system.
2368 The
2369 .Fl d
2370 flag limits this to interfaces that are down, and
2371 .Fl u
2372 limits this to interfaces that are up.
2373 When no arguments are given,
2374 .Fl a
2375 is implied.
2376 .Pp
2377 The
2378 .Fl l
2379 flag may be used to list all available interfaces on the system, with
2380 no other additional information.
2381 Use of this flag is mutually exclusive
2382 with all other flags and commands, except for
2383 .Fl d
2384 (only list interfaces that are down)
2385 and
2386 .Fl u
2387 (only list interfaces that are up).
2388 .Pp
2389 The
2390 .Fl v
2391 flag may be used to get more verbose status for an interface.
2392 .Pp
2393 The
2394 .Fl C
2395 flag may be used to list all of the interface cloners available on
2396 the system, with no additional information.
2397 Use of this flag is mutually exclusive with all other flags and commands.
2398 .Pp
2399 The
2400 .Fl k
2401 flag causes keying information for the interface, if available, to be
2402 printed.
2403 For example, the values of 802.11 WEP keys will be printed, if accessible to
2404 the current user.
2405 This information is not printed by default, as it may be considered
2406 sensitive.
2407 .Pp
2408 If the network interface driver is not present in the kernel then
2409 .Nm
2410 will attempt to load it.
2411 The
2412 .Fl n
2413 flag disables this behavior.
2414 .Pp
2415 Only the super-user may modify the configuration of a network interface.
2416 .Sh DIAGNOSTICS
2417 Messages indicating the specified interface does not exist, the
2418 requested address is unknown, or the user is not privileged and
2419 tried to alter an interface's configuration.
2420 .Sh SEE ALSO
2421 .Xr netstat 1 ,
2422 .Xr carp 4 ,
2423 .Xr ifmedia 4 ,
2424 .Xr netintro 4 ,
2425 .Xr polling 4 ,
2426 .Xr vlan 4 ,
2427 .\" .Xr eon 5 ,
2428 .Xr rc 8 ,
2429 .Xr routed 8 ,
2430 .Xr sysctl 8
2431 .Sh HISTORY
2432 The
2433 .Nm
2434 utility appeared in
2435 .Bx 4.2 .
2436 .Sh BUGS
2437 Basic IPv6 node operation requires a link-local address on each
2438 interface configured for IPv6.
2439 Normally, such an address is automatically configured by the
2440 kernel on each interface added to the system; this behaviour may
2441 be disabled by setting the sysctl MIB variable
2442 .Va net.inet6.ip6.auto_linklocal
2443 to 0.
2444 .Pp
2445 If you delete such an address using
2446 .Nm ,
2447 the kernel may act very odd.
2448 Do this at your own risk.