1.\" $NetBSD: ifconfig.8,v 1.62 2002/09/30 07:37:09 grant Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)ifconfig.8 8.4 (Berkeley) 6/1/94 35.\" 36.Dd September 25, 2002 37.Dt IFCONFIG 8 38.Os 39.Sh NAME 40.Nm ifconfig 41.Nd configure network interface parameters 42.Sh SYNOPSIS 43.Nm 44.Ar interface address_family 45.Oo 46.Ar address 47.Op Ar dest_address 48.Oc 49.Op Ar parameters 50.Nm "" 51.Op Fl mL 52.Ar interface 53.Op Ar protocol_family 54.Nm "" 55.Fl a 56.Op Fl mL 57.Op Fl b 58.Op Fl d 59.Op Fl u 60.Op Fl s 61.Op Ar protocol_family 62.Nm "" 63.Fl l 64.Op Fl b 65.Op Fl d 66.Op Fl u 67.Op Fl s 68.Nm "" 69.Fl s 70.Ar interface 71.Nm "" 72.Fl C 73.Sh DESCRIPTION 74.Nm 75is used to assign an address 76to a network interface and/or configure 77network interface parameters. 78.Nm 79must be used at boot time to define the network address 80of each interface present on a machine; it may also be used at 81a later time to redefine an interface's address 82or other operating parameters. 83.Pp 84Available operands for 85.Nm "" : 86.Bl -tag -width Ds 87.It Ar address 88For the 89.Tn DARPA-Internet 90family, 91the address is either a host name present in the host name data 92base, 93.Xr hosts 5 , 94or a 95.Tn DARPA 96Internet address expressed in the Internet standard 97.Dq dot notation . 98For the Xerox Network Systems(tm) family, 99addresses are 100.Ar net:a.b.c.d.e.f , 101where 102.Ar net 103is the assigned network number 104.Pq in decimal , 105and each of the six bytes of the host number, 106.Ar a 107through 108.Ar f , 109are specified in hexadecimal. 110The host number may be omitted on Ethernet interfaces, 111which use the hardware physical address, 112and on interfaces other than the first. 113For the 114.Tn ISO 115family, addresses are specified as a long hexadecimal string, 116as in the Xerox family. 117However, two consecutive dots imply a zero 118byte, and the dots are optional, if the user wishes to 119.Pq carefully 120count out long strings of digits in network byte order. 121.It Ar address_family 122Specifies the 123.Ar address family 124which affects interpretation of the remaining parameters. 125Since an interface can receive transmissions in differing protocols 126with different naming schemes, specifying the address family is recommended. 127The address or protocol families currently 128supported are 129.Dq inet , 130.Dq inet6 , 131.Dq atalk , 132.Dq iso , 133and 134.Dq ns . 135.It Ar interface 136The 137.Ar interface 138parameter is a string of the form 139.Dq name unit , 140for example, 141.Dq en0 142.El 143.Pp 144The following parameters may be set with 145.Nm "" : 146.Bl -tag -width dest_addressxx 147.It Cm alias 148Establish an additional network address for this interface. 149This is sometimes useful when changing network numbers, and 150one wishes to accept packets addressed to the old interface. 151.It Fl alias 152Remove the specified network address alias. 153.It Cm arp 154Enable the use of the Address Resolution Protocol in mapping 155between network level addresses and link level addresses 156.Pq default . 157This is currently implemented for mapping between 158.Tn DARPA 159Internet 160addresses and Ethernet addresses. 161.It Fl arp 162Disable the use of the Address Resolution Protocol. 163.It Cm anycast 164.Pq inet6 only 165Set the IPv6 anycast address bit. 166.It Fl anycast 167.Pq inet6 only 168Clear the IPv6 anycast address bit. 169.It Cm broadcast Ar mask 170.Pq Inet only 171Specify the address to use to represent broadcasts to the 172network. 173The default broadcast address is the address with a host part of all 1's. 174.It Cm debug 175Enable driver dependent debugging code; usually, this turns on 176extra console error logging. 177.It Fl debug 178Disable driver dependent debugging code. 179.ne 1i 180.It Cm delete 181Remove the network address specified. 182This would be used if you incorrectly specified an alias, or it 183was no longer needed. 184If you have incorrectly set an NS address having the side effect 185of specifying the host portion, removing all NS addresses will 186allow you to respecify the host portion. 187.Cm delete 188does not work for IPv6 addresses. 189Use 190.Fl alias 191with explicit IPv6 address instead. 192.It Ar dest_address 193Specify the address of the correspondent on the other end 194of a point to point link. 195.It Cm down 196Mark an interface ``down''. 197When an interface is 198marked ``down'', the system will not attempt to 199transmit messages through that interface. 200If possible, the interface will be reset to disable reception as well. 201This action does not automatically disable routes using the interface. 202.It Cm ipdst 203This is used to specify an Internet host who is willing to receive 204ip packets encapsulating NS packets bound for a remote network. 205An apparent point to point link is constructed, and 206the address specified will be taken as the NS address and network 207of the destination. 208IP encapsulation of 209.Tn CLNP 210packets is done differently. 211.It Cm media Ar type 212Set the media type of the interface to 213.Ar type . 214Some interfaces support the mutually exclusive use of one of several 215different physical media connectors. 216For example, a 10Mb/s Ethernet 217interface might support the use of either 218.Tn AUI 219or twisted pair connectors. 220Setting the media type to 221.Dq 10base5 222or 223.Dq AUI 224would change the currently active connector to the AUI port. 225Setting it to 226.Dq 10baseT 227or 228.Dq UTP 229would activate twisted pair. 230Refer to the interfaces' driver 231specific man page for a complete list of the available types. 232.It Cm mediaopt Ar opts 233Set the specified media options on the interface. 234.Ar opts 235is a comma delimited list of options to apply to the interface. 236Refer to the interfaces' driver specific man page for a complete 237list of available options. 238.It Fl mediaopt Ar opts 239Disable the specified media options on the interface. 240.It Cm instance Ar minst 241Set the media instance to 242.Ar minst . 243This is useful for devices which have multiple physical layer interfaces 244.Pq PHYs . 245Setting the instance on such devices may not be strictly required 246by the network interface driver as the driver may take care of this 247automatically; see the driver's manual page for more information. 248.It Cm metric Ar n 249Set the routing metric of the interface to 250.Ar n , 251default 0. 252The routing metric is used by the routing protocol 253.Pq Xr routed 8 . 254Higher metrics have the effect of making a route 255less favorable; metrics are counted as addition hops 256to the destination network or host. 257.It Cm mtu Ar n 258Set the maximum transmission unit of the interface to 259.Ar n . 260Most interfaces don't support this option. 261.It Cm netmask Ar mask 262.Pq inet, inet6, and ISO 263Specify how much of the address to reserve for subdividing 264networks into sub-networks. 265The mask includes the network part of the local address 266and the subnet part, which is taken from the host field of the address. 267The mask can be specified as a single hexadecimal number 268with a leading 0x, with a dot-notation Internet address, 269or with a pseudo-network name listed in the network table 270.Xr networks 5 . 271The mask contains 1's for the bit positions in the 32-bit address 272which are to be used for the network and subnet parts, 273and 0's for the host part. 274The mask should contain at least the standard network portion, 275and the subnet field should be contiguous with the network 276portion. 277.Pp 278For INET and INET6 addresses, the netmask can also be given with 279slash-notation after the address 280.Pq e.g 192.168.17.3/24 . 281.\" see 282.\" Xr eon 5 . 283.It Cm nsellength Ar n 284.Pf ( Tn ISO 285only) 286This specifies a trailing number of bytes for a received 287.Tn NSAP 288used for local identification, the remaining leading part of which is 289taken to be the 290.Tn NET 291.Pq Network Entity Title . 292The default value is 1, which is conformant to US 293.Tn GOSIP . 294When an ISO address is set in an ifconfig command, 295it is really the 296.Tn NSAP 297which is being specified. 298For example, in 299.Tn US GOSIP , 30020 hex digits should be 301specified in the 302.Tn ISO NSAP 303to be assigned to the interface. 304There is some evidence that a number different from 1 may be useful 305for 306.Tn AFI 30737 type addresses. 308.It Cm nwid Ar id 309.Pq IEEE 802.11 devices only 310Configure network ID for IEEE 802.11-based wireless network interfaces. 311The 312.Ar id 313can either be any text string up to 32 characters in length, 314or a series of hexadecimal digits up to 64 digits. 315The empty string allows the interface to connect to any available 316access points. 317.It Cm nwkey Ar key 318.Pq IEEE 802.11 devices only 319Enable WEP encryption for IEEE 802.11-based wireless network interfaces 320with the 321.Ar key . 322The 323.Ar key 324can either be a string, a series of hexadecimal digits, or a set of keys 325in the form 326.Ar n:k1,k2,k3,k4 , 327where 328.Ar n 329specifies which of keys will be used for all transmitted packets, 330and four keys, 331.Ar k1 332through 333.Ar k4 , 334are configured as WEP keys. 335Note that the order must be match within same network if multiple keys 336are used. 337For IEEE 802.11 wireless network, the length of each key is restricted to 33840 bits, i.e. 5-character string or 10 hexadecimal digits, 339while the WaveLAN/IEEE Gold cards accept the 104 bits 340.Pq 13 characters 341key. 342.It Cm nwkey Cm persist 343.Pq IEEE 802.11 devices only 344Enable WEP encryption for IEEE 802.11-based wireless network interfaces 345with the persistent key written in the network card. 346.It Cm nwkey Cm persist: Ns Ar key 347.Pq IEEE 802.11 devices only 348Write the 349.Ar key 350to the persistent memory of the network card, and 351enable WEP encryption for IEEE 802.11-based wireless network interfaces 352with the 353.Ar key . 354.It Fl nwkey 355.Pq IEEE 802.11 devices only 356Disable WEP encryption for IEEE 802.11-based wireless network interfaces. 357.It Cm powersave 358.Pq IEEE 802.11 devices only 359Enable 802.11 power saving mode. 360.It Fl powersave 361.Pq IEEE 802.11 devices only 362Disable 802.11 power saving mode. 363.It Cm powersavesleep Ar duration 364.Pq IEEE 802.11 devices only 365Set the receiver sleep duration in milliseconds for 802.11 power saving mode. 366.It Cm bssid Ar bssid 367.Pq IEEE 802.11 devices only 368Set the desired BSSID for IEEE 802.11-based wireless network interfaces. 369.It Fl bssid 370.Pq IEEE 802.11 devices only 371Unset the desired BSSID for IEEE 802.11-based wireless network interfaces. 372The interface will automatically select a BSSID in this mode, which is 373the default. 374.It Cm chan Ar chan 375.Pq IEEE 802.11 devices only 376Select the channel 377.Pq radio frequency 378to be used for IEEE 802.11-based wireless network interfaces. 379.It Fl chan 380.Pq IEEE 802.11 devices only 381Unset the desired channel to be used 382for IEEE 802.11-based wireless network interfaces. 383It doesn't effect the channel to be created for IBSS or hostap mode. 384.It Cm tunnel Ar src_addr Ar dest_addr 385.Pq IP tunnel devices only 386Configure the physical source and destination address for IP tunnel 387interfaces, including 388.Xr gif 4 . 389The arguments 390.Ar src_addr 391and 392.Ar dest_addr 393are interpreted as the outer source/destination for the encapsulating 394IPv4/IPv6 header. 395.It Cm deletetunnel 396Unconfigure the physical source and destination address for IP tunnel 397interfaces previously configured with 398.Cm tunnel . 399.It Cm create 400Create the specified network pseudo-device. 401.It Cm destroy 402Destroy the specified network pseudo-device. 403.It Cm pltime Ar n 404.Pq inet6 only 405Set preferred lifetime for the address. 406.It Cm prefixlen Ar n 407.Pq inet and inet6 only 408Effect is similar to 409.Cm netmask . 410but you can specify by prefix length by digits. 411.It Cm deprecated 412.Pq inet6 only 413Set the IPv6 deprecated address bit. 414.It Fl deprecated 415.Pq inet6 only 416Clear the IPv6 deprecated address bit. 417.It Cm tentative 418.Pq inet6 only 419Set the IPv6 tentative address bit. 420.It Fl tentative 421.Pq inet6 only 422Clear the IPv6 tentative address bit. 423.It Cm eui64 424.Pq inet6 only 425Fill interface index 426.Pq lowermost 64bit of an IPv6 address 427automatically. 428.It Cm link[0-2] 429Enable special processing of the link level of the interface. 430These three options are interface specific in actual effect, however, 431they are in general used to select special modes of operation. 432An example 433of this is to enable SLIP compression, or to select the connector type 434for some ethernet cards. 435Refer to the man page for the specific driver 436for more information. 437.ne 1i 438.It Fl link[0-2] 439Disable special processing at the link level with the specified interface. 440.It Cm up 441Mark an interface ``up''. 442This may be used to enable an interface after an ``ifconfig down.'' 443It happens automatically when setting the first address on an interface. 444If the interface was reset when previously marked down, 445the hardware will be re-initialized. 446.It Cm vlan Ar tag 447If the interface is a 448.Xr vlan 4 449pseudo-interface, set the VLAN tag to 450.Ar tag . 451This is a 16-bit number which is used to create an 802.1Q VLAN header for 452packets sent from the 453.Xr vlan 4 454interface. 455Note that 456.Cm vlan 457and 458.Cm vlanif 459must be set at the same time. 460.It Cm vlanif Ar iface 461If the interface is a 462.Xr vlan 4 463pseudo-interface, associate the physical interface 464.Ar iface 465with it. 466Packets transmitted through the 467.Xr vlan 4 468interface will be diverted to the specified physical interface 469.Ar iface 470with 802.1Q VLAN encapsulation. 471Packets with 802.1Q encapsulation received 472by the physical interface with the correct VLAN tag will be diverted to the 473associated 474.Xr vlan 4 475pseudo-interface. 476The VLAN interface is assigned a copy of the physical 477interface's flags and 478.Tn Ethernet 479address. 480If the 481.Xr vlan 4 482interface already has a physical interface associated with it, this command 483will fail. 484To change the association to another physical interface, the 485existing association must be cleared first. 486Note that 487.Cm vlanif 488and 489.Cm vlan 490must be set at the same time. 491.It Cm vltime Ar n 492.Pq inet6 only 493Set valid lifetime for the address. 494.It Cm ip4csum 495Enable hardware-assisted IPv4 header checksums on interfaces that 496support it. 497.It Cm -ip4csum 498Disable hardware-assisted IPv4 header checksums on interfaces that 499support it. 500.It Cm tcp4csum 501Enable hardware-assisted TCP/IPv4 checksums on interfaces that 502support it. 503.It Cm -tcp4csum 504Disable hardware-assisted TCP/IPv4 checksums on interfaces that 505support it. 506.It Cm udp4csum 507Enable hardware-assisted UDP/IPv4 checksums on interfaces that 508support it. 509.It Cm -udp4csum 510Disable hardware-assisted UDP/IPv4 checksums on interfaces that 511support it. 512.It Cm tcp6csum 513Enable hardware-assisted TCP/IPv6 checksums on interfaces that 514support it. 515.It Cm -tcp6csum 516Disable hardware-assisted TCP/IPv6 checksums on interfaces that 517support it. 518.It Cm udp6csum 519Enable hardware-assisted UDP/IPv6 checksums on interfaces that 520support it. 521.It Cm -udp6csum 522Disable hardware-assisted UDP/IPv6 checksums on interfaces that 523support it. 524.It Cm tcp4csum-rx 525Enable hardware-assisted TCP/IPv4 checksums on interfaces that 526support it only for the in-bound direction. 527.It Cm -tcp4csum-rx 528Disable hardware-assisted TCP/IPv4 checksums on interfaces that 529support it only for the in-bound direction. 530.It Cm udp4csum-rx 531Enable hardware-assisted UDP/IPv4 checksums on interfaces that 532support it only for the in-bound direction. 533.It Cm -udp4csum-rx 534Disable hardware-assisted UDP/IPv4 checksums on interfaces that 535support it only for the in-bound direction. 536.El 537.Pp 538.Nm 539displays the current configuration for a network interface 540when no optional parameters are supplied. 541If a protocol family is specified, 542.Nm 543will report only the details specific to that protocol 544family. 545.Pp 546If the 547.Fl s 548flag is passed before an interface name, 549.Nm 550will attempt to query the interface for its media status. 551If the 552interface supports reporting media status, and it reports that it does 553not appear to be connected to a network, 554.Nm 555will exit with status of 1 556.Pq false ; 557otherwise, it will exit with a 558zero 559.Pq true 560exit status. 561Not all interface drivers support media 562status reporting. 563.Pp 564If the 565.Fl m 566flag is passed before an interface name, 567.Nm 568will display all of the supported media for the specified interface. 569If the 570.Fl L 571flag is supplied, address lifetime is displayed for IPv6 addresses, 572as time offset string. 573.Pp 574Optionally, the 575.Fl a 576flag may be used instead of an interface name. 577This flag instructs 578.Nm 579to display information about all interfaces in the system. 580.Fl d 581limits this to interfaces that are down, 582.Fl u 583limits this to interfaces that are up, 584.Fl b 585limits this to broadcast interfaces, and 586.Fl s 587omits interfaces which appear not to be connected to a network. 588.Pp 589The 590.Fl l 591flag may be used to list all available interfaces on the system, with 592no other additional information. 593Use of this flag is mutually exclusive 594with all other flags and commands, except for 595.Fl d 596.Pq only list interfaces that are down , 597.Fl u 598.Pq only list interfaces that are up , 599.Fl s 600.Pq only list interfaces that may be connected , 601.Fl b 602.Pq only list broadcast interfaces . 603.Pp 604The 605.Fl C 606flag may be used to list all of the interface cloners available on 607the system, with no additional information. 608Use of this flag is 609mutually exclusive with all other flags and commands. 610.Pp 611Only the super-user may modify the configuration of a network interface. 612.Sh DIAGNOSTICS 613Messages indicating the specified interface does not exist, the 614requested address is unknown, or the user is not privileged and 615tried to alter an interface's configuration. 616.Sh SEE ALSO 617.Xr netstat 1 , 618.Xr ifmedia 4 , 619.Xr netintro 4 , 620.Xr ifconfig.if 5 , 621.\" .Xr eon 5 , 622.Xr rc 8 , 623.Xr routed 8 624.Sh HISTORY 625The 626.Nm 627command appeared in 628.Bx 4.2 . 629