xref: /freebsd/sbin/ifconfig/ifconfig.8 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\" Copyright (c) 1983, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 4. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     From: @(#)ifconfig.8	8.3 (Berkeley) 1/5/94
29.\" $FreeBSD$
30.\"
31.Dd December 8, 2007
32.Dt IFCONFIG 8
33.Os
34.Sh NAME
35.Nm ifconfig
36.Nd configure network interface parameters
37.Sh SYNOPSIS
38.Nm
39.Op Fl L
40.Op Fl k
41.Op Fl m
42.Op Fl n
43.Ar interface
44.Op Cm create
45.Op Ar address_family
46.Oo
47.Ar address
48.Op Ar dest_address
49.Oc
50.Op Ar parameters
51.Nm
52.Ar interface
53.Cm destroy
54.Nm
55.Fl a
56.Op Fl L
57.Op Fl d
58.Op Fl m
59.Op Fl u
60.Op Fl v
61.Op Ar address_family
62.Nm
63.Fl l
64.Op Fl d
65.Op Fl u
66.Op Ar address_family
67.Nm
68.Op Fl L
69.Op Fl d
70.Op Fl k
71.Op Fl m
72.Op Fl u
73.Op Fl v
74.Op Fl C
75.Nm
76.Op Fl g Ar groupname
77.Sh DESCRIPTION
78The
79.Nm
80utility is used to assign an address
81to a network interface and/or configure
82network interface parameters.
83The
84.Nm
85utility must be used at boot time to define the network address
86of each interface present on a machine; it may also be used at
87a later time to redefine an interface's address
88or other operating parameters.
89.Pp
90The following options are available:
91.Bl -tag -width indent
92.It Ar address
93For the
94.Tn DARPA Ns -Internet
95family,
96the address is either a host name present in the host name data
97base,
98.Xr hosts 5 ,
99or a
100.Tn DARPA
101Internet address expressed in the Internet standard
102.Dq dot notation .
103.Pp
104It is also possible to use the CIDR notation (also known as the
105slash notation) to include the netmask.
106That is, one can specify an address like
107.Li 192.168.0.1/16 .
108.Pp
109For
110.Dq inet6
111family, it is also possible to specify the prefix length using the slash
112notation, like
113.Li ::1/128 .
114See the
115.Cm prefixlen
116parameter below for more information.
117.\" For the Xerox Network Systems(tm) family,
118.\" addresses are
119.\" .Ar net:a.b.c.d.e.f ,
120.\" where
121.\" .Ar net
122.\" is the assigned network number (in decimal),
123.\" and each of the six bytes of the host number,
124.\" .Ar a
125.\" through
126.\" .Ar f ,
127.\" are specified in hexadecimal.
128.\" The host number may be omitted on IEEE 802 protocol
129.\" (Ethernet, FDDI, and Token Ring) interfaces,
130.\" which use the hardware physical address,
131.\" and on interfaces other than the first.
132.\" For the
133.\" .Tn ISO
134.\" family, addresses are specified as a long hexadecimal string,
135.\" as in the Xerox family.
136.\" However, two consecutive dots imply a zero
137.\" byte, and the dots are optional, if the user wishes to (carefully)
138.\" count out long strings of digits in network byte order.
139.Pp
140The link-level
141.Pq Dq link
142address
143is specified as a series of colon-separated hex digits.
144This can be used to
145e.g.\& set a new MAC address on an ethernet interface, though the
146mechanism used is not ethernet-specific.
147If the interface is already
148up when this option is used, it will be briefly brought down and
149then brought back up again in order to ensure that the receive
150filter in the underlying ethernet hardware is properly reprogrammed.
151.It Ar address_family
152Specify the
153address family
154which affects interpretation of the remaining parameters.
155Since an interface can receive transmissions in differing protocols
156with different naming schemes, specifying the address family is recommended.
157The address or protocol families currently
158supported are
159.Dq inet ,
160.Dq inet6 ,
161.Dq atalk ,
162.Dq ipx ,
163.\" .Dq iso ,
164and
165.Dq link .
166.\" and
167.\" .Dq ns .
168The default is
169.Dq inet .
170.Dq ether
171and
172.Dq lladdr
173are synonyms for
174.Dq link .
175.It Ar dest_address
176Specify the address of the correspondent on the other end
177of a point to point link.
178.It Ar interface
179This
180parameter is a string of the form
181.Dq name unit ,
182for example,
183.Dq Li ed0 .
184.It Ar groupname
185List the interfaces in the given group.
186.El
187.Pp
188The following parameters may be set with
189.Nm :
190.Bl -tag -width indent
191.It Cm add
192Another name for the
193.Cm alias
194parameter.
195Introduced for compatibility
196with
197.Bsx .
198.It Cm alias
199Establish an additional network address for this interface.
200This is sometimes useful when changing network numbers, and
201one wishes to accept packets addressed to the old interface.
202If the address is on the same subnet as the first network address
203for this interface, a non-conflicting netmask must be given.
204Usually
205.Li 0xffffffff
206is most appropriate.
207.It Fl alias
208Remove the network address specified.
209This would be used if you incorrectly specified an alias, or it
210was no longer needed.
211If you have incorrectly set an NS address having the side effect
212of specifying the host portion, removing all NS addresses will
213allow you to respecify the host portion.
214.It Cm anycast
215(Inet6 only.)
216Specify that the address configured is an anycast address.
217Based on the current specification,
218only routers may configure anycast addresses.
219Anycast address will not be used as source address of any of outgoing
220IPv6 packets.
221.It Cm arp
222Enable the use of the Address Resolution Protocol
223.Pq Xr arp 4
224in mapping
225between network level addresses and link level addresses (default).
226This is currently implemented for mapping between
227.Tn DARPA
228Internet
229addresses and
230.Tn IEEE
231802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses).
232.It Fl arp
233Disable the use of the Address Resolution Protocol
234.Pq Xr arp 4 .
235.It Cm staticarp
236If the Address Resolution Protocol is enabled,
237the host will only reply to requests for its addresses,
238and will never send any requests.
239.It Fl staticarp
240If the Address Resolution Protocol is enabled,
241the host will perform normally,
242sending out requests and listening for replies.
243.It Cm broadcast
244(Inet only.)
245Specify the address to use to represent broadcasts to the
246network.
247The default broadcast address is the address with a host part of all 1's.
248.It Cm debug
249Enable driver dependent debugging code; usually, this turns on
250extra console error logging.
251.It Fl debug
252Disable driver dependent debugging code.
253.It Cm promisc
254Put interface into permanently promiscuous mode.
255.It Fl promisc
256Disable permanently promiscuous mode.
257.It Cm delete
258Another name for the
259.Fl alias
260parameter.
261.It Cm down
262Mark an interface
263.Dq down .
264When an interface is marked
265.Dq down ,
266the system will not attempt to
267transmit messages through that interface.
268If possible, the interface will be reset to disable reception as well.
269This action does not automatically disable routes using the interface.
270.It Cm group Ar group-name
271Assign the interface to a
272.Dq group .
273Any interface can be in multiple groups.
274.Pp
275Cloned interfaces are members of their interface family group by default.
276For example, a PPP interface such as
277.Em ppp0
278is a member of the PPP interface family group,
279.Em ppp .
280.\" The interface(s) the default route(s) point to are members of the
281.\" .Em egress
282.\" interface group.
283.It Cm -group Ar group-name
284Remove the interface from the given
285.Dq group .
286.It Cm eui64
287(Inet6 only.)
288Fill interface index
289(lowermost 64bit of an IPv6 address)
290automatically.
291.It Cm ipdst
292This is used to specify an Internet host who is willing to receive
293IP packets encapsulating IPX packets bound for a remote network.
294An apparent point to point link is constructed, and
295the address specified will be taken as the IPX address and network
296of the destination.
297.It Cm maclabel Ar label
298If Mandatory Access Control support is enabled in the kernel,
299set the MAC label to
300.Ar label .
301.\" (see
302.\" .Xr maclabel 7 ) .
303.It Cm media Ar type
304If the driver supports the media selection system, set the media type
305of the interface to
306.Ar type .
307Some interfaces support the mutually exclusive use of one of several
308different physical media connectors.
309For example, a 10Mbit/s Ethernet
310interface might support the use of either
311.Tn AUI
312or twisted pair connectors.
313Setting the media type to
314.Cm 10base5/AUI
315would change the currently active connector to the AUI port.
316Setting it to
317.Cm 10baseT/UTP
318would activate twisted pair.
319Refer to the interfaces' driver
320specific documentation or man page for a complete list of the
321available types.
322.It Cm mediaopt Ar opts
323If the driver supports the media selection system, set the specified
324media options on the interface.
325The
326.Ar opts
327argument
328is a comma delimited list of options to apply to the interface.
329Refer to the interfaces' driver specific man page for a complete
330list of available options.
331.It Fl mediaopt Ar opts
332If the driver supports the media selection system, disable the
333specified media options on the interface.
334.It Cm mode Ar mode
335If the driver supports the media selection system, set the specified
336operating mode on the interface to
337.Ar mode .
338For IEEE 802.11 wireless interfaces that support multiple operating modes
339this directive is used to select between 802.11a
340.Pq Cm 11a ,
341802.11b
342.Pq Cm 11b ,
343and 802.11g
344.Pq Cm 11g
345operating modes.
346.It Cm inst Ar minst , Cm instance Ar minst
347Set the media instance to
348.Ar minst .
349This is useful for devices which have multiple physical layer interfaces
350.Pq PHYs .
351.It Cm name Ar name
352Set the interface name to
353.Ar name .
354.It Cm rxcsum , txcsum
355If the driver supports user-configurable checksum offloading,
356enable receive (or transmit) checksum offloading on the interface.
357Some drivers may not be able to enable these flags independently
358of each other, so setting one may also set the other.
359The driver will offload as much checksum work as it can reliably
360support, the exact level of offloading varies between drivers.
361.It Fl rxcsum , txcsum
362If the driver supports user-configurable checksum offloading,
363disable receive (or transmit) checksum offloading on the interface.
364These settings may not always be independent of each other.
365.It Cm tso
366If the driver supports
367.Xr tcp 4
368segmentation offloading, enable TSO on the interface.
369Some drivers may not be able to support TSO for
370.Xr ip 4
371and
372.Xr ip6 4
373packets, so they may enable only one of them.
374.It Fl tso
375If the driver supports
376.Xr tcp 4
377segmentation offloading, disable TSO on the interface.
378It will always disable TSO for
379.Xr ip 4
380and
381.Xr ip6 4 .
382.It Cm lro
383If the driver supports
384.Xr tcp 4
385large receive offloading, enable LRO on the interface.
386.It Fl lro
387If the driver supports
388.Xr tcp 4
389large receive offloading, disable LRO on the interface.
390.It Cm wol , wol_ucast , wol_mcast , wol_magic
391Enable Wake On Lan (WOL) support, if available.
392WOL is a facility whereby a machine in a low power state may be woken
393in response to a received packet.
394There are three types of packets that may wake a system:
395ucast (directed solely to the machine's mac address),
396mcast (directed to a broadcast or multicast address),
397or
398magic (unicast or multicast frames with a ``magic contents'').
399Not all devices support WOL, those that do indicate the mechanisms
400they support in their capabilities.
401.Cm wol
402is a synonym for enabling all available WOL mechanisms.
403To disable WOL use
404.Fl wol .
405.It Cm vlanmtu , vlanhwtag
406If the driver offers user-configurable VLAN support, enable
407reception of extended frames or tag processing in hardware,
408respectively.
409Note that this must be issued on a physical interface associated with
410.Xr vlan 4 ,
411not on a
412.Xr vlan 4
413interface itself.
414.It Fl vlanmtu , vlanhwtag
415If the driver offers user-configurable VLAN support, disable
416reception of extended frames or tag processing in hardware,
417respectively.
418.It Cm polling
419Turn on
420.Xr polling 4
421feature and disable interrupts on the interface, if driver supports
422this mode.
423.It Fl polling
424Turn off
425.Xr polling 4
426feature and enable interrupt mode on the interface.
427.It Cm create
428Create the specified network pseudo-device.
429If the interface is given without a unit number, try to create a new
430device with an arbitrary unit number.
431If creation of an arbitrary device is successful, the new device name is
432printed to standard output unless the interface is renamed or destroyed
433in the same
434.Nm
435invocation.
436.It Cm destroy
437Destroy the specified network pseudo-device.
438.It Cm plumb
439Another name for the
440.Cm create
441parameter.
442Included for
443.Tn Solaris
444compatibility.
445.It Cm unplumb
446Another name for the
447.Cm destroy
448parameter.
449Included for
450.Tn Solaris
451compatibility.
452.It Cm metric Ar n
453Set the routing metric of the interface to
454.Ar n ,
455default 0.
456The routing metric is used by the routing protocol
457.Pq Xr routed 8 .
458Higher metrics have the effect of making a route
459less favorable; metrics are counted as additional hops
460to the destination network or host.
461.It Cm mtu Ar n
462Set the maximum transmission unit of the interface to
463.Ar n ,
464default is interface specific.
465The MTU is used to limit the size of packets that are transmitted on an
466interface.
467Not all interfaces support setting the MTU, and some interfaces have
468range restrictions.
469.It Cm netmask Ar mask
470.\" (Inet and ISO.)
471(Inet only.)
472Specify how much of the address to reserve for subdividing
473networks into sub-networks.
474The mask includes the network part of the local address
475and the subnet part, which is taken from the host field of the address.
476The mask can be specified as a single hexadecimal number
477with a leading
478.Ql 0x ,
479with a dot-notation Internet address,
480or with a pseudo-network name listed in the network table
481.Xr networks 5 .
482The mask contains 1's for the bit positions in the 32-bit address
483which are to be used for the network and subnet parts,
484and 0's for the host part.
485The mask should contain at least the standard network portion,
486and the subnet field should be contiguous with the network
487portion.
488.Pp
489The netmask can also be specified in CIDR notation after the address.
490See the
491.Ar address
492option above for more information.
493.It Cm prefixlen Ar len
494(Inet6 only.)
495Specify that
496.Ar len
497bits are reserved for subdividing networks into sub-networks.
498The
499.Ar len
500must be integer, and for syntactical reason it must be between 0 to 128.
501It is almost always 64 under the current IPv6 assignment rule.
502If the parameter is omitted, 64 is used.
503.Pp
504The prefix can also be specified using the slash notation after the address.
505See the
506.Ar address
507option above for more information.
508.\" see
509.\" Xr eon 5 .
510.\" .It Cm nsellength Ar n
511.\" .Pf ( Tn ISO
512.\" only)
513.\" This specifies a trailing number of bytes for a received
514.\" .Tn NSAP
515.\" used for local identification, the remaining leading part of which is
516.\" taken to be the
517.\" .Tn NET
518.\" (Network Entity Title).
519.\" The default value is 1, which is conformant to US
520.\" .Tn GOSIP .
521.\" When an ISO address is set in an ifconfig command,
522.\" it is really the
523.\" .Tn NSAP
524.\" which is being specified.
525.\" For example, in
526.\" .Tn US GOSIP ,
527.\" 20 hex digits should be
528.\" specified in the
529.\" .Tn ISO NSAP
530.\" to be assigned to the interface.
531.\" There is some evidence that a number different from 1 may be useful
532.\" for
533.\" .Tn AFI
534.\" 37 type addresses.
535.It Cm range Ar netrange
536Under appletalk, set the interface to respond to a
537.Ar netrange
538of the form
539.Ar startnet Ns - Ns Ar endnet .
540Appletalk uses this scheme instead of
541netmasks though
542.Fx
543implements it internally as a set of netmasks.
544.It Cm remove
545Another name for the
546.Fl alias
547parameter.
548Introduced for compatibility
549with
550.Bsx .
551.It Cm phase
552The argument following this specifies the version (phase) of the
553Appletalk network attached to the interface.
554Values of 1 or 2 are permitted.
555.Sm off
556.It Cm link Op Cm 0 No - Cm 2
557.Sm on
558Enable special processing of the link level of the interface.
559These three options are interface specific in actual effect, however,
560they are in general used to select special modes of operation.
561An example
562of this is to enable SLIP compression, or to select the connector type
563for some Ethernet cards.
564Refer to the man page for the specific driver
565for more information.
566.Sm off
567.It Fl link Op Cm 0 No - Cm 2
568.Sm on
569Disable special processing at the link level with the specified interface.
570.It Cm monitor
571Put the interface in monitor mode.
572No packets are transmitted, and received packets are discarded after
573.Xr bpf 4
574processing.
575.It Fl monitor
576Take the interface out of monitor mode.
577.It Cm up
578Mark an interface
579.Dq up .
580This may be used to enable an interface after an
581.Dq Nm Cm down .
582It happens automatically when setting the first address on an interface.
583If the interface was reset when previously marked down,
584the hardware will be re-initialized.
585.El
586.Pp
587The following parameters are specific to IEEE 802.11 wireless interfaces:
588.Bl -tag -width indent
589.It Cm apbridge
590When operating as an access point, pass packets between
591wireless clients directly (default).
592To instead let them pass up through the
593system and be forwarded using some other mechanism, use
594.Fl apbridge .
595Disabling the internal bridging
596is useful when traffic is to be processed with
597packet filtering.
598.It Cm authmode Ar mode
599Set the desired authentication mode in infrastructure mode.
600Not all adaptors support all modes.
601The set of
602valid modes is
603.Cm none , open , shared
604(shared key),
605.Cm 8021x
606(IEEE 802.1x),
607and
608.Cm wpa
609(IEEE WPA/WPA2/802.11i).
610The
611.Cm 8021x
612and
613.Cm wpa
614modes are only useful when using an authentication service
615(a supplicant for client operation or an authenticator when
616operating as an access point).
617Modes are case insensitive.
618.It Cm bgscan
619Enable background scanning when operating as a station.
620Background scanning is a technique whereby a station associated to
621an access point will temporarily leave the channel to scan for
622neighboring stations.
623This allows a station to maintain a cache of nearby access points
624so that roaming between access points can be done without
625a lengthy scan operation.
626Background scanning is done only when a station is not busy and
627any outbound traffic will cancel a scan operation.
628Background scanning should never cause packets to be lost though
629there may be some small latency if outbound traffic interrupts a
630scan operation.
631By default background scanning is enabled if the device is capable.
632To disable background scanning, use
633.Fl bgscan .
634Background scanning is controlled by the
635.Cm bgscanidle
636and
637.Cm bgscanintvl
638parameters.
639Background scanning must be enabled for roaming; this is an artifact
640of the current implementation and may not be required in the future.
641.It Cm bgscanidle Ar idletime
642Set the minimum time a station must be idle (not transmitting or
643receiving frames) before a background scan is initiated.
644The
645.Ar idletime
646parameter is specified in milliseconds.
647By default a station must be idle at least 250 milliseconds before
648a background scan is initiated.
649The idle time may not be set to less than 100 milliseconds.
650.It Cm bgscanintvl Ar interval
651Set the interval at which background scanning is attempted.
652The
653.Ar interval
654parameter is specified in seconds.
655By default a background scan is considered every 300 seconds (5 minutes).
656The
657.Ar interval
658may not be set to less than 15 seconds.
659.It Cm bintval Ar interval
660Set the interval at which beacon frames are sent when operating in
661ad-hoc or ap mode.
662The
663.Ar interval
664parameter is specified in TU's (1024 usecs).
665By default beacon frames are transmitted every 100 TU's.
666.It Cm bmissthreshold Ar count
667Set the number of consecutive missed beacons at which the station
668will attempt to roam (i.e., search for a new access point).
669The
670.Ar count
671parameter must be in the range 1 to 255; though the
672upper bound may be reduced according to device capabilities.
673The default threshold is 7 consecutive missed beacons; but
674this may be overridden by the device driver.
675Another name for the
676.Cm bmissthreshold
677parameter is
678.Cm bmiss .
679.It Cm bssid Ar address
680Specify the MAC address of the access point to use when operating
681as a station in a BSS network.
682This overrides any automatic selection done by the system.
683To disable a previously selected access point, supply
684.Cm any , none ,
685or
686.Cm -
687for the address.
688This option is useful when more than one access point uses the same SSID.
689Another name for the
690.Cm bssid
691parameter is
692.Cm ap .
693.It Cm burst
694Enable packet bursting.
695Packet bursting is a transmission technique whereby the wireless
696medium is acquired once to send multiple frames and the interframe
697spacing is reduced.
698This technique can significantly increase throughput by reducing
699transmission overhead.
700Packet bursting is supported by the 802.11e QoS specification
701and some devices that do not support QoS may still be capable.
702By default packet bursting is enabled if a device is capable
703of doing it.
704To disable packet bursting, use
705.Fl burst .
706.It Cm chanlist Ar channels
707Set the desired channels to use when scanning for access
708points, neighbors in an IBSS network, or looking for unoccupied
709channels when operating as an access point.
710The set of channels is specified as a comma-separated list with
711each element in the list representing either a single channel number or a range
712of the form
713.Dq Li a-b .
714Channel numbers must be in the range 1 to 255 and be permissible
715according to the operating characteristics of the device.
716.It Cm channel Ar number
717Set a single desired channel.
718Channels range from 1 to 255, but the exact selection available
719depends on the region your adaptor was manufactured for.
720Setting
721the channel to
722.Li 0 ,
723.Cm any ,
724or
725.Cm -
726will give you the default for your adaptor.
727Some
728adaptors ignore this setting unless you are in ad-hoc mode.
729Alternatively the frequency, in megahertz, may be specified
730instead of the channel number.
731.Pp
732When there are several ways to use a channel the channel
733number/frequency may be appended with attributes to clarify.
734For example, if a device is capable of operating on channel 6
735with 802.11n and 802.11g then one can specify that g-only use
736should be used by specifying ``6:g''.
737Similarly the channel width can be specified by appending it
738with ``/''; e.g. ``6/40'' specifies a 40MHz wide channel,
739These attributes can be combined as in: ``6:ht/40''.
740The full set of flags specified following a `:'' are:
741.Cm a
742(802.11a),
743.Cm b
744(802.11b),
745.Cm d
746(Atheros Dynamic Turbo mode),
747.Cm g
748(802.11g),
749.Cm h
750or
751.Cm n
752(802.11n aka HT),
753.Cm s
754(Atheros Static Turbo mode),
755and
756.Cm t
757(Atheros Dynamic Turbo mode, or appended to ``st'' and ``dt'').
758The full set of channel widths following a '/' are:
759.Cm 5
760(5MHz aka quarter-rate channel),
761.Cm 10
762(10MHz aka half-rate channel),
763.Cm 20
764(20MHz mostly for use in specifying ht20),
765and
766.Cm 40
767(40MHz mostly for use in specifying ht40),
768In addition,
769a 40MHz HT channel specification may include the location
770of the extension channel by appending ``+'' or ``-'' for above and below,
771respectively; e.g. ``2437:ht/40+'' specifies 40MHz wide HT operation
772with the center channel at frequency 2437 and the extension channel above.
773.It Cm doth
774Enable inclusion of an 802.11h country information element in beacon
775frames transmitted when operating as an access point.
776By default 802.11h is enabled if the device is capable.
777To disable 802.11h use
778.Fl doth .
779.It Cm deftxkey Ar index
780Set the default key to use for transmission.
781Typically this is only set when using WEP encryption.
782The
783.Cm weptxkey
784is an alias for this request; it is provided for backwards compatibility.
785.It Cm dtimperiod Ar period
786Set the
787DTIM
788period for transmitting buffered multicast data frames when
789operating in ap mode.
790The
791.Ar period
792specifies the number of beacon intervals between DTIM
793and must be in the range 1 to 15.
794By default DTIM is 1 (i.e., DTIM occurs at each beacon).
795.It Cm dturbo
796Enable the use of Atheros Dynamic Turbo mode when communicating with
797another Dynamic Turbo-capable station.
798Dynamic Turbo mode is an Atheros-specific mechanism by which
799stations switch between normal 802.11 operation and a ``boosted''
800mode in which a 40MHz wide channel is used for communication.
801Stations using Dynamic Turbo mode operate boosted only when the
802channel is free of non-dturbo stations; when a non-dturbo station
803is identified on the channel all stations will automatically drop
804back to normal operation.
805By default, Dynamic Turbo mode is not enabled, even if the device is capable.
806Note that turbo mode (dynamic or static) is only allowed on some
807channels depending on the regulatory constraints; use the
808.Cm list chan
809command to identify the channels where turbo mode may be used.
810To disable Dynamic Turbo mode use
811.Fl dturbo .
812.It Cm fragthreshold Ar length
813Set the threshold for which transmitted frames are broken into fragments.
814The
815.Ar length
816argument is the frame size in bytes and must be in the range 256 to 2346.
817Setting
818.Ar length
819to
820.Li 2346 ,
821.Cm any ,
822or
823.Cm -
824disables transmit fragmentation.
825Not all adaptors honor the fragmentation threshold.
826.It Cm hidessid
827When operating as an access point, do not broadcast the SSID
828in beacon frames or respond to probe request frames unless
829they are directed to the ap (i.e., they include the ap's SSID).
830By default, the SSID is included in beacon frames and
831undirected probe request frames are answered.
832To re-enable the broadcast of the SSID etc., use
833.Fl hidessid .
834.It Cm ff
835Enable the use of Atheros Fast Frames when communicating with
836another Fast Frames-capable station.
837Fast Frames are an encapsulation technique by which two 802.3
838frames are transmitted in a single 802.11 frame.
839This can noticeably improve throughput but requires that the
840receiving station understand how to decapsulate the frame.
841Fast frame use is negotiated using the Atheros 802.11 vendor-specific
842protocol extension so enabling use is safe when communicating with
843non-Atheros devices.
844By default, use of fast frames is enabled if the device is capable.
845To explicitly disable fast frames, use
846.Fl ff .
847.It Cm list active
848Display the list of channels available for use taking into account
849any restrictions set with the
850.Cm chanlist
851directive.
852See the description of
853.Cm list chan
854for more information.
855.It Cm list caps
856Display the adaptor's capabilities, including the operating
857modes supported.
858.It Cm list chan
859Display the list of channels available for use.
860Channels are shown with their IEEE channel number, equivalent
861frequency, and usage modes.
862Channels identified as
863.Ql 11g
864are also usable in
865.Ql 11b
866mode.
867Channels identified as
868.Ql 11a Turbo
869may be used only for Atheros' Static Turbo mode
870(specified with
871. Cm mediaopt turbo ) .
872Channels marked with a
873.Ql *
874have a regulatory constraint that they be passively scanned.
875This means a station is not permitted to transmit on the channel until
876it identifies the channel is being used for 802.11 communication;
877typically by hearing a beacon frame from an access point operating
878on the channel.
879.Cm list freq
880is another way of requesting this information.
881By default a compacted list of channels is displayed; if the
882.Fl v
883option is specified then all channels are shown.
884.It Cm list mac
885Display the current MAC Access Control List state.
886Each address is prefixed with a character that indicates the
887current policy applied to it:
888.Ql +
889indicates the address is allowed access,
890.Ql -
891indicates the address is denied access,
892.Ql *
893indicates the address is present but the current policy open
894(so the ACL is not consulted).
895.It Cm list scan
896Display the access points and/or ad-hoc neighbors
897located in the vicinity.
898The
899.Fl v
900flag may be used to display long SSIDs.
901.Fl v
902also causes received information elements to be displayed symbolicaly.
903This information may be updated automatically by the adaptor
904and/or with a
905.Cm scan
906request or through background scanning.
907.Cm list ap
908is another way of requesting this information.
909.It Cm list sta
910When operating as an access point display the stations that are
911currently associated.
912When operating in ad-hoc mode display stations identified as
913neighbors in the IBSS.
914When operating in station mode display the access point.
915Capabilities advertised by the stations are described under
916the
917.Cm scan
918request.
919Depending on the capabilities of the stations the following
920flags can be included in the output:
921.Bl -tag -width 3n
922.It Li A
923Authorized.
924Indicates that the station is permitted to send/receive data frames.
925.It Li E
926Extended Rate Phy (ERP).
927Indicates that the station is operating in an 802.11g network
928using extended transmit rates.
929.It Li H
930High Throughput (HT).
931Indicates that the station is using MCS to send/receive frames.
932.It Li P
933Power Save.
934Indicates that the station is operating in power save mode.
935.It Li Q
936Quality of Service (QoS).
937Indicates that the station is using QoS encapsulation for
938data frame.
939QoS encapsulation is enabled only when WME mode is enabled.
940.El
941.Pp
942By default information elements received from associated stations
943are displayed in a short form; the
944.Fl v
945flag causes this information to be displayed symbolicaly.
946.It Cm list wme
947Display the current parameters to use when operating in WME mode.
948When WME mode is enabled for an adaptor this information will be
949displayed with the regular status; this command is mostly useful
950for examining parameters when WME mode is disabled.
951See the description of the
952.Cm wme
953directive for information on the various parameters.
954.It Cm mcastrate Ar rate
955Set the rate for transmitting multicast/broadcast frames.
956Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s.
957This rate should be valid for the current operating conditions;
958if an invalid rate is specified drivers are free to chose an
959appropriate rate.
960.It Cm powersave
961Enable powersave operation.
962When operating as a client, the station will conserve power by
963periodically turning off the radio and listening for
964messages from the access point telling it there are packets waiting.
965The station must then retrieve the packets.
966Not all devices support power save operation as a client.
967The 802.11 specification requires that all access points support
968power save but some drivers do not.
969Use
970.Fl powersave
971to disable powersave operation when operating as a client.
972.It Cm powersavesleep Ar sleep
973Set the desired max powersave sleep time in TU's (1024 usecs).
974By default the max powersave sleep time is 100 TU's.
975.It Cm protmode Ar technique
976For interfaces operating in 802.11g, use the specified
977.Ar technique
978for protecting OFDM frames in a mixed 11b/11g network.
979The set of valid techniques is
980.Cm off , cts
981(CTS to self),
982and
983.Cm rtscts
984(RTS/CTS).
985Technique names are case insensitive.
986Not all devices support
987.Cm cts
988as a protection technique.
989.It Cm pureg
990When operating as an access point in 802.11g mode allow only
99111g-capable stations to associate (11b-only stations are not
992permitted to associate).
993To allow both 11g and 11b-only stations to associate, use
994.Fl pureg .
995.It Cm roaming Ar mode
996When operating as a station, control how the system will
997behave when communication with the current access point
998is broken.
999The
1000.Ar mode
1001argument may be one of
1002.Cm device
1003(leave it to the hardware device to decide),
1004.Cm auto
1005(handle either in the device or the operating system\[em]as appropriate),
1006.Cm manual
1007(do nothing until explicitly instructed).
1008By default, the device is left to handle this if it is
1009capable; otherwise, the operating system will automatically
1010attempt to reestablish communication.
1011Manual mode is used by applications such as
1012.Xr wpa_supplicant 8
1013that want to control the selection of an access point.
1014.It Cm roam:rssi11a Ar rssi
1015Set the threshold for controlling roaming when operating in an
1016802.11a BSS.
1017The
1018.Ar rssi
1019parameter specifies the receive signal strength in dBm units
1020at which roaming should be considered.
1021If the current rssi drops below this setting and background scanning
1022is enabled, then the system will check if a more desirable access point is
1023available and switch over to it.
1024The current scan cache contents are used if they are considered
1025valid according to the
1026.Cm scanvalid
1027parameter; otherwise a background scan operation is triggered before
1028any selection occurs.
1029By default
1030.Ar rssi
1031is set to 7 dBm.
1032.It Cm roam:rssi11b Ar rssi
1033Set the threshold for controlling roaming when operating in an
1034802.11b-only BSS.
1035See
1036.Cm roam:rssi11a
1037for a description of this parameter.
1038By default
1039.Ar rssi
1040is set to 7 dBm.
1041.It Cm roam:rssi11g Ar rssi
1042Set the threshold for controlling roaming when operating in a
1043(mixed) 802.11g BSS.
1044See
1045.Cm roam:rssi11a
1046for a description of this parameter.
1047By default
1048.Ar rssi
1049is set to 7 dBm.
1050.It Cm roam:rate11a Ar rate
1051Set the threshold for controlling roaming when operating in an
1052802.11a BSS.
1053The
1054.Ar rate
1055parameter specifies the transmit rate in megabits
1056at which roaming should be considered.
1057If the current transmit rate drops below this setting and background scanning
1058is enabled, then the system will check if a more desirable access point is
1059available and switch over to it.
1060The current scan cache contents are used if they are considered
1061valid according to the
1062.Cm scanvalid
1063parameter; otherwise a background scan operation is triggered before
1064any selection occurs.
1065By default
1066.Ar rate
1067is set to 12 Mb/s.
1068.It Cm roam:rate11b Ar rate
1069Set the threshold for controlling roaming when operating in an
1070802.11b-only BSS.
1071See
1072.Cm roam:rate11a
1073for a description of this parameter.
1074By default
1075.Ar rate
1076is set to 1 Mb/s.
1077.It Cm roam:rate11g Ar rate
1078Set the threshold for controlling roaming when operating in a
1079(mixed) 802.11g BSS.
1080See
1081.Cm roam:rate11a
1082for a description of this parameter.
1083By default
1084.Ar rate
1085is set to 5 Mb/s.
1086.It Cm rtsthreshold Ar length
1087Set the threshold for which
1088transmitted frames are preceded by transmission of an
1089RTS
1090control frame.
1091The
1092.Ar length
1093argument
1094is the frame size in bytes and must be in the range 1 to 2346.
1095Setting
1096.Ar length
1097to
1098.Li 2346 ,
1099.Cm any ,
1100or
1101.Cm -
1102disables transmission of RTS frames.
1103Not all adaptors support setting the RTS threshold.
1104.It Cm ssid Ar ssid
1105Set the desired Service Set Identifier (aka network name).
1106The SSID is a string up to 32 characters
1107in length and may be specified as either a normal string or in
1108hexadecimal when preceded by
1109.Ql 0x .
1110Additionally, the SSID may be cleared by setting it to
1111.Ql - .
1112.It Cm scan
1113Initiate a scan of neighboring stations, wait for it to complete, and
1114display all stations found.
1115Only the super-user can initiate a scan.
1116Depending on the capabilities of the APs, the following
1117flags can be included in the output:
1118.Bl -tag -width 3n
1119.It Li A
1120Channel Agility.
1121Indicates that the station support channel hopping as described by the
1122IEEE 802.11b specification.
1123.It Li B
1124Packet Binary Convolution Code (PBCC).
1125A modulation alternative to the standard OFDM method.
1126.It Dv C
1127Pollreq
1128.It Dv c
1129Pollable
1130.It Dv D
1131Direct Sequence Spread Spectrum (DSSSOFDM).
1132Indicates the the station supports DSSS modulation.
1133.It Li E
1134Extended Service Set (ESS).
1135Indicates that the station is part of an infrastructure network
1136(in contrast to an IBSS/ad-hoc network).
1137.It Li I
1138IBSS/ad-hoc network.
1139Indicates that the station is part of an ad-hoc network
1140(in contrast to an ESS network).
1141.It Li P
1142Privacy.
1143Data confidentiality is required for all data frames
1144exchanged within the BSS.
1145This means that this BSS requires the station to
1146use cryptographic means such as WEP, TKIP or AES-CCMP to
1147encrypt/decrypt data frames being exchanged with others.
1148.It Dv R
1149Robust Security Network (RSN).
1150Indicates that the station supports the IEEE 802.11i authentication
1151and key management protocol.
1152.It Li S
1153Short Preamble.
1154Indicates that the network is using short preambles (defined
1155in 802.11b High Rate/DSSS PHY, short preamble utilizes a
115656 bit sync field in contrast to a 128 bit field used in long
1157preamble mode).
1158.It Li s
1159Short slot time.
1160Indicates that the network is using a short slot time.
1161.El
1162.Pp
1163Interesting information elements captured from the neighboring
1164stations are displayed at the end of each row.
1165Possible elements are:
1166.Cm WME
1167(station supports WME),
1168.Cm WPA
1169(station supports WPA),
1170.Cm RSN
1171(station supports 802.11i/RSN),
1172.Cm HT
1173(station supports 802.11n/HT communication),
1174.Cm ATH
1175(station supoprts Atheros protocol extensions),
1176.Cm VEN
1177(station supports unknown vendor-specific extensions).
1178If the
1179.Fl v
1180flag is used the information element contents will be shown.
1181.Pp
1182The
1183.Cm list scan
1184request can be used to show recent scan results without
1185initiating a new scan.
1186.Pp
1187The
1188.Fl v
1189flag may be used to prevent the shortening of long SSIDs.
1190.It Cm scanvalid Ar threshold
1191Set the maximum time the scan cache contents are considered valid;
1192i.e. will be used without first triggering a scan operation to
1193refresh the data.
1194The
1195.Ar threshold
1196parameter is specified in seconds and defaults to 60 seconds.
1197The minimum setting for
1198.Ar threshold
1199is 10 seconds.
1200One should take care setting this threshold; if it is set too low
1201then attempts to roam to another access point may trigger unnecessary
1202background scan operations.
1203.It Cm stationname Ar name
1204Set the name of this station.
1205The station name is not part of the IEEE 802.11
1206protocol though some interfaces support it.
1207As such it only
1208seems to be meaningful to identical or virtually identical equipment.
1209Setting the station name is identical in syntax to setting the SSID.
1210.It Cm txpower Ar power
1211Set the power used to transmit frames.
1212The
1213.Ar power
1214argument is specified in .5 dBm units.
1215Out of range values are truncated.
1216Typically only a few discreet power settings are available and
1217the driver will use the setting closest to the specified value.
1218Not all adaptors support changing the transmit power.
1219.It Cm wepmode Ar mode
1220Set the desired WEP mode.
1221Not all adaptors support all modes.
1222The set of valid modes is
1223.Cm off , on ,
1224and
1225.Cm mixed .
1226The
1227.Cm mixed
1228mode explicitly tells the adaptor to allow association with access
1229points which allow both encrypted and unencrypted traffic.
1230On these adaptors,
1231.Cm on
1232means that the access point must only allow encrypted connections.
1233On other adaptors,
1234.Cm on
1235is generally another name for
1236.Cm mixed .
1237Modes are case insensitive.
1238.It Cm weptxkey Ar index
1239Set the WEP key to be used for transmission.
1240This is the same as setting the default transmission key with
1241.Cm deftxkey .
1242.It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key
1243Set the selected WEP key.
1244If an
1245.Ar index
1246is not given, key 1 is set.
1247A WEP key will be either 5 or 13
1248characters (40 or 104 bits) depending of the local network and the
1249capabilities of the adaptor.
1250It may be specified either as a plain
1251string or as a string of hexadecimal digits preceded by
1252.Ql 0x .
1253For maximum portability, hex keys are recommended;
1254the mapping of text keys to WEP encryption is usually driver-specific.
1255In particular, the
1256.Tn Windows
1257drivers do this mapping differently to
1258.Fx .
1259A key may be cleared by setting it to
1260.Ql - .
1261If WEP is supported then there are at least four keys.
1262Some adaptors support more than four keys.
1263If that is the case, then the first four keys
1264(1-4) will be the standard temporary keys and any others will be adaptor
1265specific keys such as permanent keys stored in NVRAM.
1266.It Cm wme
1267Enable Wireless Multimedia Extensions (WME) support, if available,
1268for the specified interface.
1269WME is a subset of the IEEE 802.11e standard to support the
1270efficient communication of realtime and multimedia data.
1271To disable WME support, use
1272.Fl wme .
1273.Pp
1274The following parameters are meaningful only when WME support is in use.
1275Parameters are specified per-AC (Access Category) and
1276split into those that are used by a station when acting
1277as an access point and those for client stations in the BSS.
1278The latter are received from the access point and may not be changed
1279(at the station).
1280The following Access Categories are recognized:
1281.Pp
1282.Bl -tag -width ".Cm AC_BK" -compact
1283.It Cm AC_BE
1284(or
1285.Cm BE )
1286best effort delivery,
1287.It Cm AC_BK
1288(or
1289.Cm BK )
1290background traffic,
1291.It Cm AC_VI
1292(or
1293.Cm VI )
1294video traffic,
1295.It Cm AC_VO
1296(or
1297.Cm VO )
1298voice traffic.
1299.El
1300.Pp
1301AC parameters are case-insensitive.
1302Traffic classification is done in the operating system using the
1303vlan priority associated with data frames or the
1304ToS (Type of Service) indication in IP-encapsulated frames.
1305If neither information is present, traffic is assigned to the
1306Best Effort (BE) category.
1307.Bl -tag -width indent
1308.It Cm ack Ar ac
1309Set the ACK policy for QoS transmissions by the local station;
1310this controls whether or not data frames transmitted by a station
1311require an ACK response from the receiving station.
1312To disable waiting for an ACK use
1313.Fl ack .
1314This parameter is applied only to the local station.
1315.It Cm acm Ar ac
1316Enable the Admission Control Mandatory (ACM) mechanism
1317for transmissions by the local station.
1318To disable the ACM use
1319.Fl acm .
1320On stations in a BSS this parameter is read-only and indicates
1321the setting received from the access point.
1322NB: ACM is not supported right now.
1323.It Cm aifs Ar ac Ar count
1324Set the Arbitration Inter Frame Spacing (AIFS)
1325channel access parameter to use for transmissions
1326by the local station.
1327On stations in a BSS this parameter is read-only and indicates
1328the setting received from the access point.
1329.It Cm cwmin Ar ac Ar count
1330Set the CWmin channel access parameter to use for transmissions
1331by the local station.
1332On stations in a BSS this parameter is read-only and indicates
1333the setting received from the access point.
1334.It Cm cwmax Ar ac Ar count
1335Set the CWmax channel access parameter to use for transmissions
1336by the local station.
1337On stations in a BSS this parameter is read-only and indicates
1338the setting received from the access point.
1339.It Cm txoplimit Ar ac Ar limit
1340Set the Transmission Opportunity Limit channel access parameter
1341to use for transmissions by the local station.
1342This parameter defines an interval of time when a WME station
1343has the right to initiate transmissions onto the wireless medium.
1344On stations in a BSS this parameter is read-only and indicates
1345the setting received from the access point.
1346.It Cm bss:aifs Ar ac Ar count
1347Set the AIFS channel access parameter to send to stations in a BSS.
1348This parameter is meaningful only when operating in ap mode.
1349.It Cm bss:cwmin Ar ac Ar count
1350Set the CWmin channel access parameter to send to stations in a BSS.
1351This parameter is meaningful only when operating in ap mode.
1352.It Cm bss:cwmax Ar ac Ar count
1353Set the CWmax channel access parameter to send to stations in a BSS.
1354This parameter is meaningful only when operating in ap mode.
1355.It Cm bss:txoplimit Ar ac Ar limit
1356Set the TxOpLimit channel access parameter to send to stations in a BSS.
1357This parameter is meaningful only when operating in ap mode.
1358.El
1359.El
1360.Pp
1361The following parameters support an optional access control list
1362feature available with some adaptors when operating in ap mode; see
1363.Xr wlan_acl 4 .
1364This facility allows an access point to accept/deny association
1365requests based on the MAC address of the station.
1366Note that this feature does not significantly enhance security
1367as MAC address spoofing is easy to do.
1368.Bl -tag -width indent
1369.It Cm mac:add Ar address
1370Add the specified MAC address to the database.
1371Depending on the policy setting association requests from the
1372specified station will be allowed or denied.
1373.It Cm mac:allow
1374Set the ACL policy to permit association only by
1375stations registered in the database.
1376.It Cm mac:del Ar address
1377Delete the specified MAC address from the database.
1378.It Cm mac:deny
1379Set the ACL policy to deny association only by
1380stations registered in the database.
1381.It Cm mac:kick Ar address
1382Force the specified station to be deauthenticated.
1383This typically is done to block a station after updating the
1384address database.
1385.It Cm mac:open
1386Set the ACL policy to allow all stations to associate.
1387.It Cm mac:flush
1388Delete all entries in the database.
1389.El
1390.Pp
1391The following parameters are for compatibility with other systems:
1392.Bl -tag -width indent
1393.It Cm nwid Ar ssid
1394Another name for the
1395.Cm ssid
1396parameter.
1397Included for
1398.Nx
1399compatibility.
1400.It Cm station Ar name
1401Another name for the
1402.Cm stationname
1403parameter.
1404Included for
1405.Bsx
1406compatibility.
1407.It Cm wep
1408Another way of saying
1409.Cm wepmode on .
1410Included for
1411.Bsx
1412compatibility.
1413.It Fl wep
1414Another way of saying
1415.Cm wepmode off .
1416Included for
1417.Bsx
1418compatibility.
1419.It Cm nwkey key
1420Another way of saying:
1421.Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" .
1422Included for
1423.Nx
1424compatibility.
1425.It Cm nwkey Xo
1426.Sm off
1427.Ar n : k1 , k2 , k3 , k4
1428.Sm on
1429.Xc
1430Another way of saying
1431.Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" .
1432Included for
1433.Nx
1434compatibility.
1435.It Fl nwkey
1436Another way of saying
1437.Cm wepmode off .
1438Included for
1439.Nx
1440compatibility.
1441.El
1442.Pp
1443The following parameters are specific to bridge interfaces:
1444.Bl -tag -width indent
1445.It Cm addm Ar interface
1446Add the interface named by
1447.Ar interface
1448as a member of the bridge.
1449The interface is put into promiscuous mode
1450so that it can receive every packet sent on the network.
1451.It Cm deletem Ar interface
1452Remove the interface named by
1453.Ar interface
1454from the bridge.
1455Promiscuous mode is disabled on the interface when
1456it is removed from the bridge.
1457.It Cm maxaddr Ar size
1458Set the size of the bridge address cache to
1459.Ar size .
1460The default is 100 entries.
1461.It Cm timeout Ar seconds
1462Set the timeout of address cache entries to
1463.Ar seconds
1464seconds.
1465If
1466.Ar seconds
1467is zero, then address cache entries will not be expired.
1468The default is 240 seconds.
1469.It Cm addr
1470Display the addresses that have been learned by the bridge.
1471.It Cm static Ar interface-name Ar address
1472Add a static entry into the address cache pointing to
1473.Ar interface-name .
1474Static entries are never aged out of the cache or re-placed, even if the
1475address is seen on a different interface.
1476.It Cm deladdr Ar address
1477Delete
1478.Ar address
1479from the address cache.
1480.It Cm flush
1481Delete all dynamically-learned addresses from the address cache.
1482.It Cm flushall
1483Delete all addresses, including static addresses, from the address cache.
1484.It Cm discover Ar interface
1485Mark an interface as a
1486.Dq discovering
1487interface.
1488When the bridge has no address cache entry
1489(either dynamic or static)
1490for the destination address of a packet,
1491the bridge will forward the packet to all
1492member interfaces marked as
1493.Dq discovering .
1494This is the default for all interfaces added to a bridge.
1495.It Cm -discover Ar interface
1496Clear the
1497.Dq discovering
1498attribute on a member interface.
1499For packets without the
1500.Dq discovering
1501attribute, the only packets forwarded on the interface are broadcast
1502or multicast packets and packets for which the destination address
1503is known to be on the interface's segment.
1504.It Cm learn Ar interface
1505Mark an interface as a
1506.Dq learning
1507interface.
1508When a packet arrives on such an interface, the source
1509address of the packet is entered into the address cache as being a
1510destination address on the interface's segment.
1511This is the default for all interfaces added to a bridge.
1512.It Cm -learn Ar interface
1513Clear the
1514.Dq learning
1515attribute on a member interface.
1516.It Cm sticky Ar interface
1517Mark an interface as a
1518.Dq sticky
1519interface.
1520Dynamically learned address entries are treated at static once entered into
1521the cache.
1522Sticky entries are never aged out of the cache or replaced, even if the
1523address is seen on a different interface.
1524.It Cm -sticky Ar interface
1525Clear the
1526.Dq sticky
1527attribute on a member interface.
1528.It Cm private Ar interface
1529Mark an interface as a
1530.Dq private
1531interface.
1532A private interface does not forward any traffic to any other port that is also
1533a private interface.
1534.It Cm -private Ar interface
1535Clear the
1536.Dq private
1537attribute on a member interface.
1538.It Cm span Ar interface
1539Add the interface named by
1540.Ar interface
1541as a span port on the bridge.
1542Span ports transmit a copy of every frame received by the bridge.
1543This is most useful for snooping a bridged network passively on
1544another host connected to one of the span ports of the bridge.
1545.It Cm -span Ar interface
1546Delete the interface named by
1547.Ar interface
1548from the list of span ports of the bridge.
1549.It Cm stp Ar interface
1550Enable Spanning Tree protocol on
1551.Ar interface .
1552The
1553.Xr if_bridge 4
1554driver has support for the IEEE 802.1D Spanning Tree protocol (STP).
1555Spanning Tree is used to detect and remove loops in a network topology.
1556.It Cm -stp Ar interface
1557Disable Spanning Tree protocol on
1558.Ar interface .
1559This is the default for all interfaces added to a bridge.
1560.It Cm edge Ar interface
1561Set
1562.Ar interface
1563as an edge port.
1564An edge port connects directly to end stations cannot create bridging
1565loops in the network, this allows it to transition straight to forwarding.
1566.It Cm -edge Ar interface
1567Disable edge status on
1568.Ar interface .
1569.It Cm autoedge Ar interface
1570Allow
1571.Ar interface
1572to automatically detect edge status.
1573This is the default for all interfaces added to a bridge.
1574.It Cm -autoedge Ar interface
1575Disable automatic edge status on
1576.Ar interface .
1577.It Cm ptp Ar interface
1578Set the
1579.Ar interface
1580as a point to point link.
1581This is required for straight transitions to forwarding and
1582should be enabled on a direct link to another RSTP capable switch.
1583.It Cm -ptp Ar interface
1584Disable point to point link status on
1585.Ar interface .
1586This should be disabled for a half duplex link and for an interface
1587connected to a shared network segment,
1588like a hub or a wireless network.
1589.It Cm autoptp Ar interface
1590Automatically detect the point to point status on
1591.Ar interface
1592by checking the full duplex link status.
1593This is the default for interfaces added to the bridge.
1594.It Cm -autoptp Ar interface
1595Disable automatic point to point link detection on
1596.Ar interface .
1597.It Cm maxage Ar seconds
1598Set the time that a Spanning Tree protocol configuration is valid.
1599The default is 20 seconds.
1600The minimum is 6 seconds and the maximum is 40 seconds.
1601.It Cm fwddelay Ar seconds
1602Set the time that must pass before an interface begins forwarding
1603packets when Spanning Tree is enabled.
1604The default is 15 seconds.
1605The minimum is 4 seconds and the maximum is 30 seconds.
1606.It Cm hellotime Ar seconds
1607Set the time between broadcasting of Spanning Tree protocol
1608configuration messages.
1609The hello time may only be changed when operating in legacy stp mode.
1610The default is 2 seconds.
1611The minimum is 1 second and the maximum is 2 seconds.
1612.It Cm priority Ar value
1613Set the bridge priority for Spanning Tree.
1614The default is 32768.
1615The minimum is 0 and the maximum is 61440.
1616.It Cm proto Ar value
1617Set the Spanning Tree protocol.
1618The default is rstp.
1619The available options are stp and rstp.
1620.It Cm holdcnt Ar value
1621Set the transmit hold count for Spanning Tree.
1622This is the number of packets transmitted before being rate limited.
1623The default is 6.
1624The minimum is 1 and the maximum is 10.
1625.It Cm ifpriority Ar interface Ar value
1626Set the Spanning Tree priority of
1627.Ar interface
1628to
1629.Ar value .
1630The default is 128.
1631The minimum is 0 and the maximum is 240.
1632.It Cm ifpathcost Ar interface Ar value
1633Set the Spanning Tree path cost of
1634.Ar interface
1635to
1636.Ar value .
1637The default is calculated from the link speed.
1638To change a previously selected path cost back to automatic, set the
1639cost to 0.
1640The minimum is 1 and the maximum is 200000000.
1641.It Cm ifmaxaddr Ar interface Ar size
1642Set the maximum number of hosts allowed from an interface, packets with unknown
1643source addresses are dropped until an existing host cache entry expires or is
1644removed.
1645Set to 0 to disable.
1646.El
1647.Pp
1648The following parameters are specific to lagg interfaces:
1649.Bl -tag -width indent
1650.It Cm laggport Ar interface
1651Add the interface named by
1652.Ar interface
1653as a port of the aggregation interface.
1654.It Cm -laggport Ar interface
1655Remove the interface named by
1656.Ar interface
1657from the aggregation interface.
1658.It Cm laggproto Ar proto
1659Set the aggregation protocol.
1660The default is failover.
1661The available options are failover, fec, lacp, loadbalance, roundrobin and
1662none.
1663.El
1664.Pp
1665The following parameters are specific to IP tunnel interfaces,
1666.Xr gif 4 :
1667.Bl -tag -width indent
1668.It Cm tunnel Ar src_addr dest_addr
1669Configure the physical source and destination address for IP tunnel
1670interfaces.
1671The arguments
1672.Ar src_addr
1673and
1674.Ar dest_addr
1675are interpreted as the outer source/destination for the encapsulating
1676IPv4/IPv6 header.
1677.It Fl tunnel
1678Unconfigure the physical source and destination address for IP tunnel
1679interfaces previously configured with
1680.Cm tunnel .
1681.It Cm deletetunnel
1682Another name for the
1683.Fl tunnel
1684parameter.
1685.El
1686.Pp
1687The following parameters are specific to
1688.Xr pfsync 4
1689interfaces:
1690.Bl -tag -width indent
1691.It Cm maxupd Ar n
1692Set the maximum number of updates for a single state which
1693can be collapsed into one.
1694This is an 8-bit number; the default value is 128.
1695.El
1696.Pp
1697The following parameters are specific to
1698.Xr vlan 4
1699interfaces:
1700.Bl -tag -width indent
1701.It Cm vlan Ar vlan_tag
1702Set the VLAN tag value to
1703.Ar vlan_tag .
1704This value is a 16-bit number which is used to create an 802.1Q
1705VLAN header for packets sent from the
1706.Xr vlan 4
1707interface.
1708Note that
1709.Cm vlan
1710and
1711.Cm vlandev
1712must both be set at the same time.
1713.It Cm vlandev Ar iface
1714Associate the physical interface
1715.Ar iface
1716with a
1717.Xr vlan 4
1718interface.
1719Packets transmitted through the
1720.Xr vlan 4
1721interface will be
1722diverted to the specified physical interface
1723.Ar iface
1724with 802.1Q VLAN encapsulation.
1725Packets with 802.1Q encapsulation received
1726by the parent interface with the correct VLAN tag will be diverted to
1727the associated
1728.Xr vlan 4
1729pseudo-interface.
1730The
1731.Xr vlan 4
1732interface is assigned a
1733copy of the parent interface's flags and the parent's ethernet address.
1734The
1735.Cm vlandev
1736and
1737.Cm vlan
1738must both be set at the same time.
1739If the
1740.Xr vlan 4
1741interface already has
1742a physical interface associated with it, this command will fail.
1743To
1744change the association to another physical interface, the existing
1745association must be cleared first.
1746.Pp
1747Note: if the hardware tagging capability
1748is set on the parent interface, the
1749.Xr vlan 4
1750pseudo
1751interface's behavior changes:
1752the
1753.Xr vlan 4
1754interface recognizes that the
1755parent interface supports insertion and extraction of VLAN tags on its
1756own (usually in firmware) and that it should pass packets to and from
1757the parent unaltered.
1758.It Fl vlandev Op Ar iface
1759If the driver is a
1760.Xr vlan 4
1761pseudo device, disassociate the parent interface from it.
1762This breaks the link between the
1763.Xr vlan 4
1764interface and its parent,
1765clears its VLAN tag, flags and its link address and shuts the interface down.
1766The
1767.Ar iface
1768argument is useless and hence deprecated.
1769.El
1770.Pp
1771The following parameters are specific to
1772.Xr carp 4
1773interfaces:
1774.Bl -tag -width indent
1775.It Cm advbase Ar seconds
1776Specifies the base of the advertisement interval in seconds.
1777The acceptable values are 1 to 255.
1778The default value is 1.
1779.\" The default value is
1780.\" .Dv CARP_DFLTINTV .
1781.It Cm advskew Ar interval
1782Specifies the skew to add to the base advertisement interval to
1783make one host advertise slower than another host.
1784It is specified in 1/256 of seconds.
1785The acceptable values are 1 to 254.
1786The default value is 0.
1787.It Cm pass Ar phrase
1788Set the authentication key to
1789.Ar phrase .
1790.It Cm vhid Ar n
1791Set the virtual host ID.
1792This is a required setting.
1793Acceptable values are 1 to 255.
1794.El
1795.Pp
1796The
1797.Nm
1798utility displays the current configuration for a network interface
1799when no optional parameters are supplied.
1800If a protocol family is specified,
1801.Nm
1802will report only the details specific to that protocol family.
1803.Pp
1804If the
1805.Fl m
1806flag is passed before an interface name,
1807.Nm
1808will display the capability list and all
1809of the supported media for the specified interface.
1810If
1811.Fl L
1812flag is supplied, address lifetime is displayed for IPv6 addresses,
1813as time offset string.
1814.Pp
1815Optionally, the
1816.Fl a
1817flag may be used instead of an interface name.
1818This flag instructs
1819.Nm
1820to display information about all interfaces in the system.
1821The
1822.Fl d
1823flag limits this to interfaces that are down, and
1824.Fl u
1825limits this to interfaces that are up.
1826When no arguments are given,
1827.Fl a
1828is implied.
1829.Pp
1830The
1831.Fl l
1832flag may be used to list all available interfaces on the system, with
1833no other additional information.
1834Use of this flag is mutually exclusive
1835with all other flags and commands, except for
1836.Fl d
1837(only list interfaces that are down)
1838and
1839.Fl u
1840(only list interfaces that are up).
1841.Pp
1842The
1843.Fl v
1844flag may be used to get more verbose status for an interface.
1845.Pp
1846The
1847.Fl C
1848flag may be used to list all of the interface cloners available on
1849the system, with no additional information.
1850Use of this flag is mutually exclusive with all other flags and commands.
1851.Pp
1852The
1853.Fl k
1854flag causes keying information for the interface, if available, to be
1855printed.
1856For example, the values of 802.11 WEP keys will be printed, if accessible to
1857the current user.
1858This information is not printed by default, as it may be considered
1859sensitive.
1860.Pp
1861If the network interface driver is not present in the kernel then
1862.Nm
1863will attempt to load it.
1864The
1865.Fl n
1866flag disables this behavior.
1867.Pp
1868Only the super-user may modify the configuration of a network interface.
1869.Sh NOTES
1870The media selection system is relatively new and only some drivers support
1871it (or have need for it).
1872.Sh EXAMPLES
1873Assign the IPv4 address
1874.Li 192.0.2.10 ,
1875with a network mask of
1876.Li 255.255.255.0 ,
1877to the interface
1878.Li fxp0 :
1879.Dl # ifconfig fxp0 inet 192.0.2.10 netmask 255.255.255.0
1880.Pp
1881Add the IPv4 address
1882.Li 192.0.2.45 ,
1883with the CIDR network prefix
1884.Li /28 ,
1885to the interface
1886.Li ed0 ,
1887using
1888.Cm add
1889as a synonym for the canonical form of the option
1890.Cm alias :
1891.Dl # ifconfig ed0 inet 192.0.2.45/28 add
1892.Pp
1893Remove the IPv4 address
1894.Li 192.0.2.45
1895from the interface
1896.Li ed0 :
1897.Dl # ifconfig ed0 inet 192.0.2.45 -alias
1898.Pp
1899Add the IPv6 address
1900.Li 2001:DB8:DBDB::123/48
1901to the interface
1902.Li em0 :
1903.Dl # ifconfig em0 inet6 2001:db8:bdbd::123 prefixlen 48 alias
1904Note that lower case hexadecimal IPv6 addresses are acceptable.
1905.Pp
1906Remove the IPv6 address added in the above example,
1907using the
1908.Li /
1909character as shorthand for the network prefix,
1910and using
1911.Cm delete
1912as a synonym for the canonical form of the option
1913.Fl alias :
1914.Dl # ifconfig em0 inet6 2001:db8:bdbd::123/48 delete
1915.Pp
1916Configure the interface
1917.Li xl0 ,
1918to use 100baseTX, full duplex Ethernet media options:
1919.Dl # ifconfig xl0 media 100baseTX mediaopt full-duplex
1920.Pp
1921Create the software network interface
1922.Li gif1 :
1923.Dl # ifconfig gif1 create
1924.Pp
1925Destroy the software network interface
1926.Li gif1 :
1927.Dl # ifconfig gif1 destroy
1928.Sh DIAGNOSTICS
1929Messages indicating the specified interface does not exist, the
1930requested address is unknown, or the user is not privileged and
1931tried to alter an interface's configuration.
1932.Sh SEE ALSO
1933.Xr netstat 1 ,
1934.Xr carp 4 ,
1935.Xr netintro 4 ,
1936.Xr pfsync 4 ,
1937.Xr polling 4 ,
1938.Xr vlan 4 ,
1939.\" .Xr eon 5 ,
1940.Xr rc 8 ,
1941.Xr routed 8 ,
1942.Xr sysctl 8
1943.Sh HISTORY
1944The
1945.Nm
1946utility appeared in
1947.Bx 4.2 .
1948.Sh BUGS
1949Basic IPv6 node operation requires a link-local address on each
1950interface configured for IPv6.
1951Normally, such an address is automatically configured by the
1952kernel on each interface added to the system; this behaviour may
1953be disabled by setting the sysctl MIB variable
1954.Va net.inet6.ip6.auto_linklocal
1955to 0.
1956.Pp
1957If you delete such an address using
1958.Nm ,
1959the kernel may act very odd.
1960Do this at your own risk.
1961