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