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