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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgment: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94 33.\" $FreeBSD$ 34.\" 35.Dd July 2, 2001 36.Dt IFCONFIG 8 37.Os 38.Sh NAME 39.Nm ifconfig 40.Nd configure network interface parameters 41.Sh SYNOPSIS 42.Nm 43.Op Fl L 44.Op Fl m 45.Ar interface 46.Op Cm create 47.Op Ar address_family 48.Oo 49.Ar address 50.Op Ar dest_address 51.Oc 52.Op Ar parameters 53.Nm 54.Ar interface 55.Cm destroy 56.Nm 57.Fl a 58.Op Fl L 59.Op Fl d 60.Op Fl m 61.Op Fl u 62.Op Ar address_family 63.Nm 64.Fl l 65.Op Fl d 66.Op Fl u 67.Op Ar address_family 68.Nm 69.Op Fl L 70.Op Fl d 71.Op Fl m 72.Op Fl u 73.Op Fl C 74.Sh DESCRIPTION 75The 76.Nm 77utility is used to assign an address 78to a network interface and/or configure 79network interface parameters. 80The 81.Nm 82utility must be used at boot time to define the network address 83of each interface present on a machine; it may also be used at 84a later time to redefine an interface's address 85or other operating parameters. 86.Pp 87The following options are available: 88.Bl -tag -width indent 89.It Ar address 90For the 91.Tn DARPA Ns -Internet 92family, 93the address is either a host name present in the host name data 94base, 95.Xr hosts 5 , 96or a 97.Tn DARPA 98Internet address expressed in the Internet standard 99.Dq dot notation . 100.Pp 101It is also possible to use the CIDR notation (also known as the 102slash notation) to include the netmask. 103That is, one can specify an address like 104.Li 192.168.0.1/16 . 105.Pp 106For 107.Dq inet6 108family, it is also possible to specify the prefix length using the slash 109notation, like 110.Li ::1/128 . 111See the 112.Cm prefixlen 113parameter below for more information. 114.\" For the Xerox Network Systems(tm) family, 115.\" addresses are 116.\" .Ar net:a.b.c.d.e.f , 117.\" where 118.\" .Ar net 119.\" is the assigned network number (in decimal), 120.\" and each of the six bytes of the host number, 121.\" .Ar a 122.\" through 123.\" .Ar f , 124.\" are specified in hexadecimal. 125.\" The host number may be omitted on IEEE 802 protocol 126.\" (Ethernet, FDDI, and Token Ring) interfaces, 127.\" which use the hardware physical address, 128.\" and on interfaces other than the first. 129.\" For the 130.\" .Tn ISO 131.\" family, addresses are specified as a long hexadecimal string, 132.\" as in the Xerox family. 133.\" However, two consecutive dots imply a zero 134.\" byte, and the dots are optional, if the user wishes to (carefully) 135.\" count out long strings of digits in network byte order. 136.Pp 137The link-level 138.Pq Dq link 139address 140is specified as a series of colon-separated hex digits. 141This can be used to 142e.g. set a new MAC address on an ethernet interface, though the 143mechanism used is not ethernet-specific. 144If the interface is already 145up when this option is used, it will be briefly brought down and 146then brought back up again in order to ensure that the receive 147filter in the underlying ethernet hardware is properly reprogrammed. 148.It Ar address_family 149Specify the 150address family 151which affects interpretation of the remaining parameters. 152Since an interface can receive transmissions in differing protocols 153with different naming schemes, specifying the address family is recommended. 154The address or protocol families currently 155supported are 156.Dq inet , 157.Dq inet6 , 158.Dq atalk , 159.Dq ipx , 160.\" .Dq iso , 161and 162.Dq link . 163.\" and 164.\" .Dq ns . 165The default is 166.Dq inet . 167.Dq ether 168and 169.Dq lladdr 170are synonyms for 171.Dq link . 172.It Ar dest_address 173Specify the address of the correspondent on the other end 174of a point to point link. 175.It Ar interface 176This 177parameter is a string of the form 178.Dq name unit , 179for example, 180.Dq Li ed0 . 181.El 182.Pp 183The following parameters may be set with 184.Nm : 185.Bl -tag -width indent 186.It Cm add 187Another name for the 188.Cm alias 189parameter. 190Introduced for compatibility 191with 192.Bsx . 193.It Cm alias 194Establish an additional network address for this interface. 195This is sometimes useful when changing network numbers, and 196one wishes to accept packets addressed to the old interface. 197If the address is on the same subnet as the first network address 198for this interface, a non-conflicting netmask must be given. 199Usually 200.Li 0xffffffff 201is most appropriate. 202.It Fl alias 203Remove the network address specified. 204This would be used if you incorrectly specified an alias, or it 205was no longer needed. 206If you have incorrectly set an NS address having the side effect 207of specifying the host portion, removing all NS addresses will 208allow you to respecify the host portion. 209.It Cm anycast 210(Inet6 only.) 211Specify that the address configured is an anycast address. 212Based on the current specification, 213only routers may configure anycast addresses. 214Anycast address will not be used as source address of any of outgoing 215IPv6 packets. 216.It Cm arp 217Enable the use of the Address Resolution Protocol 218.Pq Xr arp 4 219in mapping 220between network level addresses and link level addresses (default). 221This is currently implemented for mapping between 222.Tn DARPA 223Internet 224addresses and 225.Tn IEEE 226802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses). 227.It Fl arp 228Disable the use of the Address Resolution Protocol 229.Pq Xr arp 4 . 230.It Cm broadcast 231(Inet only.) 232Specify the address to use to represent broadcasts to the 233network. 234The default broadcast address is the address with a host part of all 1's. 235.It Cm debug 236Enable driver dependent debugging code; usually, this turns on 237extra console error logging. 238.It Fl debug 239Disable driver dependent debugging code. 240.It Cm delete 241Another name for the 242.Fl alias 243parameter. 244.It Cm down 245Mark an interface 246.Dq down . 247When an interface is marked 248.Dq down , 249the system will not attempt to 250transmit messages through that interface. 251If possible, the interface will be reset to disable reception as well. 252This action does not automatically disable routes using the interface. 253.It Cm eui64 254(Inet6 only.) 255Fill interface index 256.Pq lowermost 64bit of an IPv6 address 257automatically. 258.\" .It Cm ipdst 259.\" This is used to specify an Internet host who is willing to receive 260.\" ip packets encapsulating NS packets bound for a remote network. 261.\" An apparent point to point link is constructed, and 262.\" the address specified will be taken as the NS address and network 263.\" of the destination. 264.\" IP encapsulation of 265.\" .Tn CLNP 266.\" packets is done differently. 267.It Cm media Ar type 268If the driver supports the media selection system, set the media type 269of the interface to 270.Ar type . 271Some interfaces support the mutually exclusive use of one of several 272different physical media connectors. 273For example, a 10Mb/s Ethernet 274interface might support the use of either 275.Tn AUI 276or twisted pair connectors. 277Setting the media type to 278.Dq 10base5/AUI 279would change the currently active connector to the AUI port. 280Setting it to 281.Dq 10baseT/UTP 282would activate twisted pair. 283Refer to the interfaces' driver 284specific documentation or man page for a complete list of the 285available types. 286.It Cm mediaopt Ar opts 287If the driver supports the media selection system, set the specified 288media options on the interface. 289The 290.Ar opts 291argument 292is a comma delimited list of options to apply to the interface. 293Refer to the interfaces' driver specific man page for a complete 294list of available options. 295.It Fl mediaopt Ar opts 296If the driver supports the media selection system, disable the 297specified media options on the interface. 298.It Cm tunnel Ar src_addr dest_addr 299(IP tunnel devices only.) 300Configure the physical source and destination address for IP tunnel 301interfaces 302.Pq Xr gif 4 . 303The arguments 304.Ar src_addr 305and 306.Ar dest_addr 307are interpreted as the outer source/destination for the encapsulating 308IPv4/IPv6 header. 309.It Cm deletetunnel 310Unconfigure the physical source and destination address for IP tunnel 311interfaces previously configured with 312.Cm tunnel . 313.It Cm create 314Create the specified network pseudo-device. 315If the interface is given without a unit number, try to create a new 316device with an arbitrary unit number. 317If creation of an arbitrary device is successful, the new device name is 318printed to standard output. 319.It Cm destroy 320Destroy the specified network pseudo-device. 321.It Cm plumb 322Another name for the 323.Cm create 324parameter. 325Included for 326.Tn Solaris 327compatibility. 328.It Cm unplumb 329Another name for the 330.Cm destroy 331parameter. 332Included for 333.Tn Solaris 334compatibility. 335.It Cm vlan Ar vlan_tag 336If the interface is a vlan pseudo interface, set the vlan tag value 337to 338.Ar vlan_tag . 339This value is a 16-bit number which is used to create an 802.1Q 340vlan header for packets sent from the vlan interface. 341Note that 342.Cm vlan 343and 344.Cm vlandev 345must both be set at the same time. 346.It Cm vlandev Ar iface 347If the interface is a vlan pseudo device, associate physical interface 348.Ar iface 349with it. 350Packets transmitted through the vlan interface will be 351diverted to the specified physical interface 352.Ar iface 353with 802.1Q vlan encapsulation. 354Packets with 802.1Q encapsulation received 355by the parent interface with the correct vlan tag will be diverted to 356the associated vlan pseudo-interface. 357The vlan interface is assigned a 358copy of the parent interface's flags and the parent's ethernet address. 359The 360.Cm vlandev 361and 362.Cm vlan 363must both be set at the same time. 364If the vlan interface already has 365a physical interface associated with it, this command will fail. 366To 367change the association to another physical interface, the existing 368association must be cleared first. 369.Pp 370Note: if the 371.Cm link0 372flag is set on the vlan interface, the vlan pseudo 373interface's behavior changes: the 374.Cm link0 375tells the vlan interface that the 376parent interface supports insertion and extraction of vlan tags on its 377own (usually in firmware) and that it should pass packets to and from 378the parent unaltered. 379.It Fl vlandev Ar iface 380If the driver is a vlan pseudo device, disassociate the physical interface 381.Ar iface 382from it. 383This breaks the link between the vlan interface and its parent, 384clears its vlan tag, flags and its link address and shuts the interface down. 385.It Cm metric Ar n 386Set the routing metric of the interface to 387.Ar n , 388default 0. 389The routing metric is used by the routing protocol 390.Pq Xr routed 8 . 391Higher metrics have the effect of making a route 392less favorable; metrics are counted as addition hops 393to the destination network or host. 394.It Cm mtu Ar n 395Set the maximum transmission unit of the interface to 396.Ar n , 397default is interface specific. 398The MTU is used to limit the size of packets that are transmitted on an 399interface. 400Not all interfaces support setting the MTU, and some interfaces have 401range restrictions. 402.It Cm netmask Ar mask 403.\" (Inet and ISO.) 404(Inet only.) 405Specify how much of the address to reserve for subdividing 406networks into sub-networks. 407The mask includes the network part of the local address 408and the subnet part, which is taken from the host field of the address. 409The mask can be specified as a single hexadecimal number 410with a leading 411.Ql 0x , 412with a dot-notation Internet address, 413or with a pseudo-network name listed in the network table 414.Xr networks 5 . 415The mask contains 1's for the bit positions in the 32-bit address 416which are to be used for the network and subnet parts, 417and 0's for the host part. 418The mask should contain at least the standard network portion, 419and the subnet field should be contiguous with the network 420portion. 421.Pp 422The netmask can also be specified in CIDR notation after the address. 423See the 424.Ar address 425option above for more information. 426.It Cm prefixlen Ar len 427(Inet6 only.) 428Specify that 429.Ar len 430bits are reserved for subdividing networks into sub-networks. 431The 432.Ar len 433must be integer, and for syntactical reason it must be between 0 to 128. 434It is almost always 64 under the current IPv6 assignment rule. 435If the parameter is omitted, 64 is used. 436.Pp 437The prefix can also be specified using the slash notation after the address. 438See the 439.Ar address 440option above for more information. 441.\" see 442.\" Xr eon 5 . 443.\" .It Cm nsellength Ar n 444.\" .Pf ( Tn ISO 445.\" only) 446.\" This specifies a trailing number of bytes for a received 447.\" .Tn NSAP 448.\" used for local identification, the remaining leading part of which is 449.\" taken to be the 450.\" .Tn NET 451.\" (Network Entity Title). 452.\" The default value is 1, which is conformant to US 453.\" .Tn GOSIP . 454.\" When an ISO address is set in an ifconfig command, 455.\" it is really the 456.\" .Tn NSAP 457.\" which is being specified. 458.\" For example, in 459.\" .Tn US GOSIP , 460.\" 20 hex digits should be 461.\" specified in the 462.\" .Tn ISO NSAP 463.\" to be assigned to the interface. 464.\" There is some evidence that a number different from 1 may be useful 465.\" for 466.\" .Tn AFI 467.\" 37 type addresses. 468.It Cm range Ar netrange 469Under appletalk, set the interface to respond to a 470.Ar netrange 471of the form 472.Ar startnet Ns - Ns Ar endnet . 473Appletalk uses this scheme instead of 474netmasks though 475.Fx 476implements it internally as a set of netmasks. 477.It Cm remove 478Another name for the 479.Fl alias 480parameter. 481Introduced for compatibility 482with 483.Bsx . 484.It Cm phase 485The argument following this specifies the version (phase) of the 486Appletalk network attached to the interface. 487Values of 1 or 2 are permitted. 488.Sm off 489.It Cm link Op Cm 0 No - Cm 2 490.Sm on 491Enable special processing of the link level of the interface. 492These three options are interface specific in actual effect, however, 493they are in general used to select special modes of operation. 494An example 495of this is to enable SLIP compression, or to select the connector type 496for some Ethernet cards. 497Refer to the man page for the specific driver 498for more information. 499.Sm off 500.It Fl link Op Cm 0 No - Cm 2 501.Sm on 502Disable special processing at the link level with the specified interface. 503.It Cm up 504Mark an interface 505.Dq up . 506This may be used to enable an interface after an 507.Dq Nm Cm down . 508It happens automatically when setting the first address on an interface. 509If the interface was reset when previously marked down, 510the hardware will be re-initialized. 511.It Cm ssid Ar ssid 512For IEEE 802.11 wireless interfaces, set the desired Service Set 513Identifier (aka network name). 514The SSID is a string up to 32 characters 515in length and may be specified as either a normal string or in 516hexadecimal when proceeded by 517.Ql 0x . 518Additionally, the SSID may be cleared by setting it to 519.Ql - . 520.It Cm nwid Ar ssid 521Another name for the 522.Cm ssid 523parameter. 524Included for 525.Nx 526compatibility. 527.It Cm stationname Ar name 528For IEEE 802.11 wireless interfaces, set the name of this station. 529It appears that the station name is not really part of the IEEE 802.11 530protocol though all interfaces seem to support it. 531As such it only 532seems to be meaningful to identical or virtually identical equipment. 533Setting the station name is identical in syntax to setting the SSID. 534.It Cm station Ar name 535Another name for the 536.Cm stationname 537parameter. 538Included for 539.Bsx 540compatibility. 541.It Cm channel Ar number 542For IEEE 802.11 wireless interfaces, set the desired channel. 543Channels range from 1 to 14, but the exact selection available 544depends on the region your adaptor was manufactured for. 545Setting 546the channel to 0 will give you the default for your adaptor. 547Many 548adaptors ignore this setting unless you are in ad-hoc mode. 549.It Cm authmode Ar mode 550For IEEE 802.11 wireless interfaces, set the desired authentication mode 551in infrastructure mode. 552Not all adaptors support all modes. 553The set of 554valid modes is 555.Dq none , 556.Dq open , 557and 558.Dq shared . 559Modes are case insensitive. 560.It Cm powersave 561For IEEE 802.11 wireless interfaces, enable powersave mode. 562.It Fl powersave 563For IEEE 802.11 wireless interfaces, disable powersave mode. 564.It Cm powersavesleep Ar sleep 565For IEEE 802.11 wireless interfaces, set the desired max powersave sleep 566time in milliseconds. 567.It Cm wepmode Ar mode 568For IEEE 802.11 wireless interfaces, set the desired WEP mode. 569Not all adaptors support all modes. 570The set of valid modes is 571.Dq off , 572.Dq on , 573and 574.Dq mixed . 575.Dq Mixed 576mode explicitly tells the adaptor to allow association with access 577points which allow both encrypted and unencrypted traffic. 578On these adaptors, 579.Dq on 580means that the access point must only allow encrypted connections. 581On other adaptors, 582.Dq on 583is generally another name for 584.Dq mixed . 585Modes are case insensitive. 586.It Cm weptxkey Ar index 587For IEEE 802.11 wireless interfaces, set the WEP key to be used for 588transmission. 589.It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key 590For IEEE 802.11 wireless interfaces, set the selected WEP key. 591If an 592.Ar index 593is not given, key 1 is set. 594A WEP key will be either 5 or 13 595characters (40 or 104 bits) depending of the local network and the 596capabilities of the adaptor. 597It may be specified either as a plain 598string or as a string of hexadecimal digits proceeded by 599.Ql 0x . 600A key may be cleared by setting it to 601.Ql - . 602If WEP is supported then there are at least four keys. 603Some adaptors support more than four keys. 604If that is the case, then the first four keys 605(1-4) will be the standard temporary keys and any others will be adaptor 606specific keys such as permanent keys stored in NVRAM. 607.It Cm wep 608Another way of saying 609.Cm wepmode on . 610Included for 611.Bsx 612compatibility. 613.It Fl wep 614Another way of saying 615.Cm wepmode off . 616Included for 617.Bsx 618compatibility. 619.It Cm nwkey key 620Another way of saying: 621.Pp 622.Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" . 623.Pp 624Included for 625.Nx 626compatibility. 627.It Cm nwkey Xo 628.Sm off 629.Ar n : k1 , k2 , k3 , k4 630.Sm on 631.Xc 632Another way of saying 633.Pp 634.Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" . 635.Pp 636Included for 637.Nx 638compatibility. 639.It Fl nwkey 640Another way of saying 641.Cm wepmode off . 642.Pp 643Included for 644.Nx 645compatibility. 646.El 647.Pp 648The 649.Nm 650utility displays the current configuration for a network interface 651when no optional parameters are supplied. 652If a protocol family is specified, 653.Nm 654will report only the details specific to that protocol family. 655.Pp 656If the driver does supports the media selection system, the supported 657media list will be included in the output. 658.Pp 659If the 660.Fl m 661flag is passed before an interface name, 662.Nm 663will display all 664of the supported media for the specified interface. 665If 666.Fl L 667flag is supplied, address lifetime is displayed for IPv6 addresses, 668as time offset string. 669.Pp 670Optionally, the 671.Fl a 672flag may be used instead of an interface name. 673This flag instructs 674.Nm 675to display information about all interfaces in the system. 676The 677.Fl d 678flag limits this to interfaces that are down, and 679.Fl u 680limits this to interfaces that are up. 681When no arguments are given, 682.Fl a 683is implied. 684.Pp 685The 686.Fl l 687flag may be used to list all available interfaces on the system, with 688no other additional information. 689Use of this flag is mutually exclusive 690with all other flags and commands, except for 691.Fl d 692(only list interfaces that are down) 693and 694.Fl u 695(only list interfaces that are up). 696.Pp 697The 698.Fl C 699flag may be used to list all of the interface cloners available on 700the system, with no additional information. 701Use of this flag is mutually exclusive with all other flags and commands. 702.Pp 703Only the super-user may modify the configuration of a network interface. 704.Sh NOTES 705The media selection system is relatively new and only some drivers support 706it (or have need for it). 707.Sh DIAGNOSTICS 708Messages indicating the specified interface does not exist, the 709requested address is unknown, or the user is not privileged and 710tried to alter an interface's configuration. 711.Sh BUGS 712IPv6 link-local addresses are required for several basic communication 713between IPv6 node. 714If they are deleted by 715.Nm 716manually, the kernel might show very strange behavior. 717So, such manual deletions are strongly discouraged. 718.Sh SEE ALSO 719.Xr netstat 1 , 720.Xr netintro 4 , 721.\" .Xr eon 5 , 722.Xr rc 8 , 723.Xr routed 8 724.Sh HISTORY 725The 726.Nm 727utility appeared in 728.Bx 4.2 . 729