1.\" $MirOS: src/sbin/ifconfig/ifconfig.8,v 1.4 2009/10/27 16:31:32 tg Exp $ 2.\" $OpenBSD: ifconfig.8,v 1.93 2004/12/01 22:30:53 jmc Exp $ 3.\" $NetBSD: ifconfig.8,v 1.11 1996/01/04 21:27:29 pk Exp $ 4.\" $FreeBSD: ifconfig.8,v 1.16 1998/02/01 07:03:29 steve Exp $ 5.\" 6.\" Copyright (c) 1983, 1991, 1993 7.\" The Regents of the University of California. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)ifconfig.8 8.4 (Berkeley) 6/1/94 34.\" 35.Dd September 3, 1998 36.Dt IFCONFIG 8 37.Os 38.Sh NAME 39.Nm ifconfig 40.Nd configure network interface parameters 41.Sh SYNOPSIS 42.Nm ifconfig 43.Ar interface 44.Op Ar address_family 45.Oo 46.Ar address 47.Op Ar dest_address 48.Oc 49.Op Ar parameters 50.Nm ifconfig 51.Fl A | Am | a | am 52.Op Ar address_family 53.Nm ifconfig 54.Fl C 55.Nm ifconfig 56.Fl l 57.Nm ifconfig 58.Fl m 59.Ar interface 60.Op Ar address_family 61.Nm ifconfig 62.Ar interface 63.Cm create 64.Nm ifconfig 65.Ar interface 66.Cm destroy 67.Nm ifconfig 68.Ar carp-interface 69.Cm vhid 70.Ar host-id 71.Nm ifconfig 72.Ar pfsync-interface 73.Cm syncif 74.Ar iface 75.Nm 76.Ar pppoe-interface 77.Oo 78.Cm pppoedev 79.Ar parent-interface 80.Oc 81.Oo 82.Cm pppoesvc 83.Ar service 84.Oc 85.Oo 86.Cm pppoeac 87.Ar access-concentrator 88.Oc 89.Nm ifconfig 90.Ar tunnel-interface 91.Cm tunnel 92.Ar src_address dest_address 93.Nm ifconfig 94.Ar tunnel-interface 95.Cm deletetunnel 96.Nm ifconfig 97.Ar vlan-interface 98.Cm vlan 99.Ar vlan-tag 100.Cm vlandev 101.Ar parent-interface 102.Sh DESCRIPTION 103The 104.Nm 105utility is used to assign an address 106to a network interface and/or configure 107network interface parameters. 108.Nm 109must be used at boot-time to define the network address 110of each interface present on a machine; it may also be used at 111a later time to redefine an interface's address 112or other operating parameters. 113To configure a bridge interface, use the 114.Xr brconfig 8 115program instead. 116.Pp 117.Nm 118displays the current configuration for a network interface 119when no optional parameters are supplied. 120If a protocol family is specified, 121.Nm 122will report only the details specific to that protocol family. 123.Pp 124Only the superuser may modify the configuration of a network interface. 125.Pp 126The options are as follows: 127.Bl -tag -width Ds 128.It Fl A 129Causes full interface alias information for each interface to 130be displayed. 131.It Fl Am 132The same as the 133.Fl A 134option, 135but additionally prints interface media information for all interfaces. 136.It Fl a 137Causes 138.Nm 139to print information on all interfaces. 140The protocol family may be specified as well. 141.It Fl am 142The same as the 143.Fl a 144option, 145but additionally prints interface media information for all interfaces. 146.It Fl C 147Print the names of all network pseudo-devices that 148can be created dynamically at runtime using 149.Cm ifconfig create . 150.It Fl l 151Print the names of all network interfaces, except some virtual interfaces 152like pflog, pfsync, enc, irip, separated by spaces. 153.It Fl m Ar interface 154Print media information for a given 155.Ar interface . 156.It Ar address 157For the 158.Tn DARPA 159Internet 160family, 161the address is either a host name present in the host name database, 162.Xr hosts 5 , 163or a 164.Tn DARPA 165Internet address expressed in the Internet standard 166.Dq dot notation . 167.Pp 168Internet version 6 addresses are either a host name present 169in the host name database, 170.Xr hosts 5 , 171or an Internet version 6 address in standard colon separated form, as 172described in the 173.Xr inet 3 174manual page. 175.Pp 176For the Xerox Network Systems(tm) and Internetwork Packet Exchange families, 177addresses are of the form 178.Dq net:a.b.c.d.e.f , 179where 180.Dq net 181is the assigned network number (in decimal), 182and each of the six bytes of the host number, 183.Dq a 184through 185.Dq f , 186are specified in hexadecimal. 187The host number may be omitted on Ethernet interfaces, 188which use the hardware physical address, 189and on interfaces other than the first. 190.Tn AppleTalk 191(LLAP) addresses are specified as 192.Dq nn.na 193.Pq Dq Network Number.Node Address . 194Node addresses are divided into two classes: User Node IDs and Server Node IDs. 1951-127($01-$7F) are for User Node IDs while 128-254($80-$FE) 196are used for Server Node IDs. 197Node 0($00) is not allowed (unknown) 198while Node 255($FF) is reserved for the AppleTalk broadcast hardware 199address (broadcast ID). 200.Pp 201.Tn IPX 202addresses are specified as listed in the 203.Xr ipx 3 204manual page. 205.It Ar address_family 206Specifies the address family 207which affects interpretation of the remaining parameters. 208Since an interface can receive transmissions in differing protocols 209with different naming schemes, specifying the address family is recommended. 210The address or protocol families currently 211supported are 212.Dq inet , 213.Dq inet6 , 214.Dq atalk 215and 216.Dq ipx . 217.It Ar interface 218The 219.Ar interface 220parameter is a string of the form 221.Dq name unit , 222for example, 223.Dq en0 . 224If no optional parameters are supplied, this string can instead be just 225.Dq name . 226In this case, all interfaces of that type will be displayed. 227For example, 228.Dq carp 229will display the current configuration of all 230.Xr carp 4 231interfaces. 232.El 233.Pp 234The following parameters may be set with 235.Nm : 236.Bl -tag -width dest_addressxx 237.It Cm 802.2 802.2tr 802.3 snap EtherII 238Set the 239.Xr ipx 3 240frame type to be either 802.2, 802.2tr, 802.3, snap, or Ethernet II. 241.It Cm advbase Ar n 242If the driver is a 243.Xr carp 4 244pseudo-device, set the base advertisement interval to 245.Ar n 246seconds. 247This is an 8-bit number; the default value is 1 second. 248.It Cm advskew Ar n 249If the driver is a 250.Xr carp 4 251pseudo-device, skew the advertisement interval by 252.Ar n . 253This is an 8-bit number; the default value is 0. 254.Pp 255Taken together the 256.Cm advbase 257and 258.Cm advskew 259indicate how frequently, in seconds, the host will advertise the fact that it 260considers itself master of the virtual host. 261The formula is 262.Cm advbase 263+ 264.Cm ( advskew 265/ 255 ). 266If the master does not advertise within three times this interval, this host 267will begin advertising as master. 268.It Cm alias 269Establish an additional network address for this interface. 270This is sometimes useful when changing network numbers, and 271one wishes to accept packets addressed to the old interface. 272.It Fl alias 273Remove the specified network address alias. 274.It Cm anycast 275(inet6 only) 276Set the IPv6 anycast address bit. 277.It Fl anycast 278(inet6 only) 279Clear the IPv6 anycast address bit. 280.It Cm arp 281Enable the use of the Address Resolution Protocol 282(``ARP''; 283see 284.Xr arp 4 ) 285in mapping 286between network level addresses and link level addresses (default). 287This is currently implemented for mapping between 288.Tn DARPA 289Internet 290addresses and Ethernet addresses. 291.It Fl arp 292Disable the use of ARP. 293.It Cm broadcast Ar addr 294(inet only) 295Specify the address to use to represent broadcasts to the 296network. 297The default broadcast address is the address with a host part of all 1's. 298.It Cm create 299Create the specified network pseudo-device. 300At least the following devices can be created on demand: 301.Pp 302.Xr bridge 4 , 303.Xr carp 4 , 304.Xr gif 4 , 305.Xr gre 4 , 306.Xr lo 4 , 307.Xr ppp 4 , 308.Xr pppoe 4 , 309.Xr sl 4 , 310.Xr tun 4 , 311.Xr vlan 4 312.It Cm debug 313Enable driver-dependent debugging code; usually, this turns on 314extra console error logging. 315.It Fl debug 316Disable driver-dependent debugging code. 317.It Cm delete 318Remove the network address specified. 319This would be used if you incorrectly specified an alias, or it 320was no longer needed. 321.It Cm deletetunnel 322Removes the source and destination tunnel addresses, 323configured onto a tunnel interface. 324.It Ar dest_address 325Specify the address of the correspondent on the other end 326of a point-to-point link. 327.It Cm destroy 328Destroy the specified network pseudo-device. 329.It Cm down 330Mark an interface 331.Dq down . 332When an interface is marked 333.Dq down , 334the system will not attempt to 335transmit messages through that interface. 336If possible, the interface will be reset to disable reception as well. 337This action automatically disables routes using the interface. 338.It Cm eui64 339(inet6 only) 340Fill the interface index 341.Pq the lowermost 64th bit of an IPv6 address 342automatically. 343.It Cm instance Ar minst 344Set the media instance to 345.Ar minst . 346This is useful for devices which have multiple physical layer interfaces 347(PHYs). 348Setting the instance on such devices may not be strictly required 349by the network interface driver as the driver may take care of this 350automatically; see the driver's manual page for more information. 351.It Cm link[0-2] 352Enable special processing of the link level of the interface. 353These three options are interface specific in actual effect; however, 354they are in general used to select special modes of operation. 355An example 356of this is to enable SLIP compression, or to select the connector type 357for some Ethernet cards. 358Refer to the man page for the specific driver for more information. 359.It Fl link[0-2] 360Disable special processing at the link level with the specified interface. 361.It Cm maxupd Ar n 362If the driver is a 363.Xr pfsync 4 364pseudo-device, indicate the maximum number 365of updates for a single state which can be collapsed into one. 366This is an 8-bit number; the default value is 128. 367.It Cm media Ar type 368Set the media type of the interface to 369.Ar type . 370Some interfaces support the mutually exclusive use of one of several 371different physical media connectors. 372For example, a 10Mb/s Ethernet interface might support the use of either 373.Tn AUI 374or twisted pair connectors. 375Setting the media type to 376.Dq 10base5 377or 378.Dq AUI 379would change the currently active connector to the AUI port. 380Setting it to 381.Dq 10baseT 382or 383.Dq UTP 384would activate twisted pair. 385Refer to the interface's driver-specific man page for a complete 386list of the available types, 387or use 388.Bd -literal -offset indent 389$ ifconfig -m interface 390.Ed 391.Pp 392for a listing of choices. 393.It Cm mediaopt Ar opts 394Set the specified media options on the interface. 395.Ar opts 396is a comma delimited list of options to apply to the interface. 397Refer to the interface's driver-specific man page for a complete 398list of available options, 399or use 400.Bd -literal -offset indent 401$ ifconfig -m interface 402.Ed 403.Pp 404for a listing of choices. 405.It Fl mediaopt Ar opts 406Disable the specified media options on the interface. 407.It Cm metric Ar nhops 408Set the routing metric of the interface to 409.Ar nhops , 410default 0. 411The routing metric is used by the routing protocol 412(see 413.Xr routed 8 ) . 414Higher metrics have the effect of making a route 415less favorable; metrics are counted as addition hops 416to the destination network or host. 417.It Cm mtu Ar value 418Set the MTU for this device to the given 419.Ar value . 420Cloned routes will inherit this value as a default. 421Currently, not all devices support setting the MTU. 422.It Cm netmask Ar mask 423(inet, inet6) 424Specify how much of the address to reserve for subdividing 425networks into subnetworks. 426The mask includes the network part of the local address 427and the subnet part, which is taken from the host field of the address. 428The mask can be specified as a single hexadecimal number 429with a leading 0x, with a dot-notation Internet address, 430or with a pseudo-network name listed in the network table 431.Xr networks 5 . 432The mask contains 1's for the bit positions in the 32-bit address 433which are to be used for the network and subnet parts, 434and 0's for the host part. 435The mask should contain at least the standard network portion, 436and the subnet field should be contiguous with the network 437portion. 438.It Cm nwkey Ar key 439(IEEE 802.11 devices only) 440Enable WEP encryption for IEEE 802.11-based wireless network interfaces 441using the specified 442.Ar key . 443The 444.Ar key 445can either be a string, a series of hexadecimal digits (preceded by 446.So 0x Sc ) , 447or a set of keys 448of the form 449.Dq n:k1,k2,k3,k4 450where 451.Sq n 452specifies which of the keys will be used for transmitted packets, 453and the four keys, 454.Dq k1 455through 456.Dq k4 , 457are configured as WEP keys. 458If a set of keys is specified, a comma 459.Pq Sq \&, 460within the key must be escaped with a backslash. 461Note that if multiple keys are used, their order must be the same within 462the network. 463For IEEE 802.11 wireless networks, the length of each key is restricted to 46440 bits, i.e. a 5-character string or 10 hexadecimal digits. 465WaveLAN/IEEE Gold and newer Prism cards will also accept a 104-bit 466(13-character) key. 467.It Fl nwkey 468(IEEE 802.11 devices only) 469Disable WEP encryption for IEEE 802.11-based wireless network interfaces. 470.It Cm nwkey Cm persist 471(IEEE 802.11 devices only) 472Enable WEP encryption for IEEE 802.11-based wireless network interfaces 473with the persistent key stored in the network card. 474.It Cm nwkey Cm persist : Ns Ar key 475(IEEE 802.11 devices only) 476Write 477.Ar key 478to the persistent memory of the network card, and 479enable WEP encryption for IEEE 802.11-based wireless network interfaces 480using that 481.Ar key . 482.It Cm pass Ar passphrase 483If the driver is a 484.Xr carp 4 485pseudo-device, set the authentication key to 486.Ar passphrase . 487There is no passphrase by default. 488.It Cm phase Ar n 489The argument 490.Ar n 491specifies the version (phase) of the 492AppleTalk network attached to the interface. 493Values of 1 or 2 are permitted. 494.It Cm pltime Ar n 495(inet6 only) 496Set preferred lifetime for the address. 497.It Cm powersave 498(IEEE 802.11 devices only) 499Enable 802.11 power saving mode. 500.It Fl powersave 501(IEEE 802.11 devices only) 502Disable 802.11 power saving mode. 503.It Cm powersavesleep Ar duration 504(IEEE 802.11 devices only) 505Set the receiver sleep duration (in milliseconds) for 802.11 power saving mode. 506.It Cm pppoeac Ar access-concentrator 507Set the name of the access-concentrator for the 508.Xr pppoe 4 509interface. 510.It Fl pppoeac 511Clear a previously set access-concentrator name. 512.It Cm pppoedev Ar parent-interface 513Set the name of the interface through which 514.Xr pppoe 4 515packets will be transmitted and received. 516.It Cm pppoesvc Ar service 517Set the service name of the 518.Xr pppoe 4 519interface. 520.It Fl pppoesvc 521Clear a previously set service name. 522.It Cm prefixlen Ar n 523(inet and inet6 only) 524Effect is similar to 525.Cm netmask , 526but you can specify prefix length by digits. 527.It Cm range Ar netrange 528Under AppleTalk, set the interface to respond to a 529.Ar netrange 530of the form 531.Dq startnet-endnet . 532AppleTalk uses this scheme instead of 533netmasks though 534.Ox 535implements it internally as a set of netmasks. 536.It Cm state Ar state 537Explicitly force the 538.Xr carp 4 539pseudo-device to enter this state. 540Valid states are 541.Ar init , 542.Ar backup , 543and 544.Ar master . 545.It Cm syncif Ar iface 546If the driver is a 547.Xr pfsync 4 548pseudo-device, use the specified interface 549to send and receive pfsync state synchronisation messages. 550.It Fl syncif 551If the driver is a 552.Xr pfsync 4 553pseudo-device, stop sending pfsync state 554synchronisation messages over the network. 555.It Cm tentative 556(inet6 only) 557Set the IPv6 tentative address bit. 558.It Fl tentative 559(inet6 only) 560Clear the IPv6 tentative address bit. 561.It Cm trailers 562Request the use of a 563.Dq trailer 564link level encapsulation when 565sending (default). 566If a network interface supports 567.Cm trailers , 568the system will, when possible, encapsulate outgoing 569messages in a manner which minimizes the number of 570memory to memory copy operations performed by the receiver. 571On networks that support ARP 572(currently, only Ethernet), 573this flag indicates that the system should request that other 574systems use trailers when sending to this host. 575Similarly, trailer encapsulations will be sent to other 576hosts that have made such requests. 577Currently used by Internet protocols only. 578.It Fl trailers 579Disable the use of a 580.Dq trailer 581link level encapsulation. 582.It Cm tunnel Ar src_address dest_address 583Set the source and destination tunnel addresses on a tunnel interface, 584including 585.Xr gif 4 . 586Packets routed to this interface will be encapsulated in 587IPv4 or IPv6, depending on the source and destination address families. 588Both addresses must be of the same family. 589.It Cm up 590Mark an interface 591.Dq up . 592This may be used to enable an interface after an 593.Cm ifconfig down . 594It happens automatically when setting the first address on an interface. 595If the interface was reset when previously marked down, 596the hardware will be re-initialized. 597.It Cm vhid Ar n 598If the driver is a 599.Xr carp 4 600pseudo-device, set the virtual host ID to 601.Ar n . 602Acceptable values are 1 to 255. 603.It Cm vlan Ar vlan_tag 604If the interface is a 605.Xr vlan 4 606pseudo-interface, set the vlan tag value 607to 608.Ar vlan_tag . 609This value is a 12-bit number which is used to create an 802.1Q 610vlan header for packets sent from the vlan interface. 611Note that 612.Cm vlan 613and 614.Cm vlandev 615must both be set at the same time. 616.It Cm vlandev Ar iface 617If the interface is a 618.Xr vlan 4 619pseudo-device, associate physical interface 620.Ar iface 621with it. 622Packets transmitted through the vlan interface will be 623diverted to the specified physical interface 624.Ar iface 625with 802.1Q vlan encapsulation. 626Packets with 802.1Q encapsulation received 627by the parent interface with the correct vlan tag will be diverted to 628the associated vlan pseudo-interface. 629The vlan interface is assigned a 630copy of the parent interface's flags and the parent's Ethernet address. 631.Cm vlandev 632and 633.Cm vlan 634must both be set at the same time. 635If the vlan interface already has 636a physical interface associated with it, this command will fail. 637To change the association to another physical interface, the existing 638association must be cleared first. 639.Pp 640Note: if the 641.Ar link0 642flag is set on the vlan interface, the vlan pseudo-interface's 643behavior changes; 644.Ar link0 645tells the vlan interface that the 646parent interface supports insertion and extraction of vlan tags on its 647own (usually in firmware) and that it should pass packets to and from 648the parent unaltered. 649.It Fl vlandev 650If the driver is a 651.Xr vlan 4 652pseudo-device, disassociate the physical interface 653from it. 654This breaks the link between the vlan interface and its parent, 655clears its vlan tag, flags, and link address, and shuts the interface down. 656.It Cm vltime Ar n 657(inet6 only) 658Set valid lifetime for the address. 659.El 660.Sh EXAMPLES 661Assign the 662.Xr inet 3 663address of 192.168.1.10 with a network mask of 664255.255.255.0 to interface fxp0: 665.Pp 666.Dl # ifconfig fxp0 inet 192.168.1.10 netmask 255.255.255.0 667.Pp 668Assign the 669.Xr ipx 3 670address of 12625920 specified in decimal to interface fxp0: 671.Pp 672.Dl # ifconfig fxp0 ipx 12625920 673.Pp 674Assign the AppleTalk network 39108 and server node 128 with a network 675range of 39107-39109 to interface fxp0 on a phase 2 AppleTalk network: 676.Pp 677.Dl # ifconfig fxp0 atalk 39108.128 range 39107-39109 phase 2 678.Pp 679Configure the xl0 interface to use 10baseT: 680.Pp 681.Dl # ifconfig xl0 media 10baseT 682.Pp 683Configure the xl0 interface to use 100baseTX, full duplex: 684.Pp 685.Dl # ifconfig xl0 media 100baseTX mediaopt full-duplex 686.Pp 687Configure the vlan0 interface for IP address 192.168.254.1, vlan tag 4, 688and vlan parent device fxp0: 689.Pp 690.Dl # ifconfig vlan0 192.168.254.1 vlan 4 vlandev fxp0 691.Pp 692Configure the carp0 interface for IP address 192.168.10.1, virtual host ID 1: 693.Pp 694.Dl # ifconfig carp0 vhid 1 192.168.10.1 695.Pp 696Create the gif1 network interface: 697.Pp 698.Dl # ifconfig gif1 create 699.Pp 700Destroy the gif1 network interface: 701.Pp 702.Dl # ifconfig gif1 destroy 703.Sh DIAGNOSTICS 704Messages indicating the specified interface does not exist, the 705requested address is unknown, or the user is not privileged and 706tried to alter an interface's configuration. 707.Sh SEE ALSO 708.Xr netstat 1 , 709.Xr inet 3 , 710.Xr ipx 3 , 711.Xr arp 4 , 712.Xr bridge 4 , 713.Xr carp 4 , 714.Xr gif 4 , 715.Xr gre 4 , 716.Xr ifmedia 4 , 717.Xr inet 4 , 718.Xr lo 4 , 719.Xr netintro 4 , 720.Xr pfsync 4 , 721.Xr ppp 4 , 722.Xr pppoe 4 , 723.Xr sl 4 , 724.Xr tun 4 , 725.Xr vlan 4 , 726.Xr hostname.if 5 , 727.Xr hosts 5 , 728.Xr networks 5 , 729.Xr brconfig 8 , 730.Xr rc 8 , 731.Xr routed 8 732.Sh HISTORY 733The 734.Nm 735command appeared in 736.Bx 4.2 . 737