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