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