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