IFCONFIG(8)             OpenBSD System Manager's Manual            IFCONFIG(8)

NAME
     ifconfig - configure network interface parameters

SYNOPSIS
     ifconfig [-AaCm] [interface] [address_family] [address [dest_address]]
              [parameters]

DESCRIPTION
     The ifconfig utility is used to assign an address to a network interface
     and/or configure network interface parameters.  Generally speaking,
     hostname.if(5) files are used at boot-time to define the network address
     of each interface present on a machine; ifconfig is used at a later time
     to redefine an interface's address or other operating parameters.  To
     configure a bridge interface, use the brconfig(8) program instead.

     ifconfig displays the current configuration for a network interface when
     no optional parameters are supplied.  If a protocol family is specified,
     ifconfig will report only the details specific to that protocol family.
     If no parameters are provided, a summary of all interfaces is provided.

     Only the superuser may modify the configuration of a network interface.

     The options are as follows:

     -A      Causes full interface alias information for each interface to be
             displayed.

     -a      Causes ifconfig to print information on all interfaces.  The pro-
             tocol family may be specified as well.  This is the default, if
             no parameters are given to ifconfig.

     -C      Print the names of all network pseudo-devices that can be created
             dynamically at runtime using ifconfig create.

     -m      Print media information for a given interface.  When combined
             with the -Aa options, additionally prints media information for
             all interfaces.

     interface
             The interface parameter is a string of the form ``name unit'',
             for example, ``en0''.  If no optional parameters are supplied,
             this string can instead be just ``name''.  In this case, all in-
             terfaces of that type will be displayed.  For example, ``carp''
             will display the current configuration of all carp(4) interfaces.

     address_family
             Specifies the address family which affects interpretation of the
             remaining parameters.  Since an interface can receive transmis-
             sions in differing protocols with different naming schemes, spec-
             ifying the address family is recommended.  The address or proto-
             col families currently supported are ``inet'', ``inet6'',
             ``atalk'', and ``ipx''.

     address
             For the DARPA Internet family, the address is either a host name
             present in the host name database, hosts(5), or a DARPA Internet
             address expressed in the Internet standard ``dot notation''.

             Internet version 6 addresses are either a host name present in
             the host name database, hosts(5), or an Internet version 6 ad-
             dress in standard colon separated form, as described in the
             inet(3) manual page.

             For the Xerox Network Systems(tm) and Internetwork Packet Ex-
             change families, addresses are of the form ``net:a.b.c.d.e.f'',
             where ``net'' is the assigned network number (in decimal), and
             each of the six bytes of the host number, ``a'' through ``f'',
             are specified in hexadecimal.  The host number may be omitted on
             Ethernet interfaces, which use the hardware physical address, and
             on interfaces other than the first.  IPX addresses are specified
             as listed in the ipx(3) manual page.

             AppleTalk (LLAP) addresses are specified as ``nn.na'' (``Network
             Number.Node Address'').  Node addresses are divided into two
             classes: User Node IDs and Server Node IDs.  1-127($01-$7F) are
             for User Node IDs while 128-254($80-$FE) are used for Server Node
             IDs.  Node 0($00) is not allowed (unknown) while Node 255($FF) is
             reserved for the AppleTalk broadcast hardware address (broadcast
             ID).

     dest_address
             Specify the address of the correspondent on the other end of a
             point-to-point link.

     The following parameters may be set with ifconfig:

     802.2 | 802.2tr | 802.3 | snap | EtherII
                     Set the ipx(3) frame type to be either 802.2, 802.2tr,
                     802.3, snap, or Ethernet II.

     alias           Establish an additional network address for this inter-
                     face.  This is sometimes useful when changing network
                     numbers, and one wishes to accept packets addressed to
                     the old interface.

     -alias          A synonym for delete.  Use of this option is discouraged
                     in favour of delete.

     arp             Enable the use of the Address Resolution Protocol (ARP)
                     in mapping between network level addresses and link level
                     addresses (default).  This is currently implemented for
                     mapping between DARPA Internet addresses and Ethernet ad-
                     dresses.

     -arp            Disable the use of ARP.

     broadcast addr  (inet only) Specify the address to use to represent
                     broadcasts to the network.  The default broadcast address
                     is the address with a host part of all 1's.

     create          Create the specified network pseudo-device.  At least the
                     following devices can be created on demand:

                     bridge(4), carp(4), gif(4), gre(4), lo(4), ppp(4),
                     pppoe(4), sl(4), trunk(4), tun(4), vlan(4)

     debug           Enable driver-dependent debugging code; usually, this
                     turns on extra console error logging.

     -debug          Disable driver-dependent debugging code.

     delete          Remove the specified network address, including any net-
                     mask or destination address configured with this address.

     description value
                     Specify a description of the interface.  This can be used
                     to label interfaces in situations where they may other-
                     wise be difficult to distinguish.

     -description    Clear the interface description.

     destroy         Destroy the specified network pseudo-device.

     down            Mark an interface ``down''.  When an interface is marked
                     ``down'', the system will not attempt to transmit mes-
                     sages through that interface.  If possible, the interface
                     will be reset to disable reception as well.  This action
                     automatically disables routes using the interface.

     group group-name
                     Assign the interface to a ``group''.  Any interface can
                     be in multiple groups.

                     For instance, such a group could be used to create a
                     hardware independent pf(4) ruleset (i.e. not one based on
                     the names of NICs) using existing (egress, carp, etc.) or
                     user-defined groups.

                     Cloned interfaces are members of their interface family
                     group by default.  For example, a PPP interface such as
                     ppp0 is a member of the PPP interface family group, ppp.
                     The interface(s) the default route(s) point to are mem-
                     bers of the egress interface group.

     -group group-name
                     Remove the interface from the given ``group''.

     instance minst  Set the media instance to minst.  This is useful for de-
                     vices which have multiple physical layer interfaces
                     (PHYs).  Setting the instance on such devices may not be
                     strictly required by the network interface driver as the
                     driver may take care of this automatically; see the driv-
                     er's manual page for more information.

     ipdst addr      This is used to specify an Internet host which is willing
                     to receive IP packets encapsulating IPX or AppleTalk
                     packets bound for a remote network.  An apparent point-
                     to-point link is constructed, and the address specified
                     will be taken as the address and network of the destina-
                     tion.  IP encapsulation of Connectionless Network Proto-
                     col (``CLNP'') packets is done differently.

     link[0-2]       Enable special processing of the link level of the inter-
                     face.  These three options are interface specific in ac-
                     tual effect; however, they are in general used to select
                     special modes of operation.  An example of this is to en-
                     able SLIP compression, or to select the connector type
                     for some Ethernet cards.  Refer to the man page for the
                     specific driver for more information.

     -link[0-2]      Disable special processing at the link level with the
                     specified interface.

     lladdr etheraddr
                     Change the link layer address (MAC address) of the inter-
                     face.  This should be specificed as six colon-separated
                     hex values.

     media type      Set the media type of the interface to type.  Some inter-
                     faces support the mutually exclusive use of one of sever-
                     al different physical media connectors.  For example, a
                     10Mb/s Ethernet interface might support the use of either
                     AUI or twisted pair connectors.  Setting the media type
                     to ``10base5'' or ``AUI'' would change the currently ac-
                     tive connector to the AUI port.  Setting it to
                     ``10baseT'' or ``UTP'' would activate twisted pair.  Re-
                     fer to the interface's driver-specific man page for a
                     complete list of the available types, or use the follow-
                     ing command for a listing of choices:

                           $ ifconfig -m interface

     mediaopt opts   Set the specified media options on the interface.  opts
                     is a comma delimited list of options to apply to the in-
                     terface.  Refer to the interface's driver-specific man
                     page for a complete list of available options, or use the
                     following command for a listing of choices:

                           $ ifconfig -m interface

     -mediaopt opts  Disable the specified media options on the interface.

     metric nhops    Set the routing metric of the interface to nhops, default
                     0.  The routing metric is used by the routing protocol
                     (see routed(8)).  Higher metrics have the effect of mak-
                     ing a route less favorable; metrics are counted as addi-
                     tion hops to the destination network or host.

     mode mode       If the driver for the interface supports the media selec-
                     tion system, set the specified operating mode on the in-
                     terface to the given mode.  For IEEE 802.11 wireless in-
                     terfaces that support multiple operating modes, this di-
                     rective is used to select between 802.11a (``11a''),
                     802.11b (``11b''), and 802.11g (``11g'') operating modes.

     mtu value       Set the MTU for this device to the given value.  Cloned
                     routes will inherit this value as a default.  Currently,
                     not all devices support setting the MTU.

     netmask mask    (inet and inet6) Specify how much of the address to re-
                     serve for subdividing networks into subnetworks.  The
                     mask includes the network part of the local address and
                     the subnet part, which is taken from the host field of
                     the address.  The mask can be specified as a single hex-
                     adecimal number with a leading 0x, with a dot-notation
                     Internet address, or with a pseudo-network name listed in
                     the network table networks(5).  The mask contains 1's for
                     the bit positions in the 32-bit address which are to be
                     used for the network and subnet parts, and 0's for the
                     host part.  The mask should contain at least the standard
                     network portion, and the subnet field should be contigu-
                     ous with the network portion.

     phase n         The argument n specifies the version (phase) of the Ap-
                     pleTalk network attached to the interface.  Values of 1
                     or 2 are permitted.

     prefixlen n     (inet and inet6 only) Effect is similar to netmask, but
                     you can specify prefix length by digits.

     range netrange  Under AppleTalk, set the interface to respond to a
                     netrange of the form ``startnet-endnet''.  AppleTalk uses
                     this scheme instead of netmasks though OpenBSD implements
                     it internally as a set of netmasks.

     timeslot timeslot_range
                     Set the timeslot range map, which is used to control
                     which channels an interface device uses.

     up              Mark an interface ``up''.  This may be used to enable an
                     interface after an ifconfig down.  It happens automati-
                     cally when setting the first address on an interface.  If
                     the interface was reset when previously marked down, the
                     hardware will be re-initialized.

     ifconfig supports a multitude of sub-types, described in the following
     sections:

           -   carp(4)
           -   IEEE 802.11 (wireless devices)
           -   inet6(4)
           -   interface groups
           -   pfsync(4)
           -   pppoe(4)
           -   sppp(4) (PPP Link Control Protocol)
           -   trunk(4)
           -   tunnel (gif(4) and gre(4))
           -   vlan(4)

CARP
     ifconfig carp-interface [advbase n] [advskew n] [carpdev iface]
     [pass passphrase] [state state] [vhid host-id]

     The options are as follows:

     advbase n
             If the driver is a carp(4) pseudo-device, set the base advertise-
             ment interval to n seconds.  This is an 8-bit number; the default
             value is 1 second.

     advskew n
             If the driver is a carp(4) pseudo-device, skew the advertisement
             interval by n.  This is an 8-bit number; the default value is 0.

     carpdev iface
             If the driver is a carp(4) pseudo-device, attach it to iface.  If
             not specified, the kernel will attempt to select an interface
             with a subnet matching that of the carp interface.

     pass passphrase
             If the driver is a carp(4) pseudo-device, set the authentication
             key to passphrase.  There is no passphrase by default.

     state state
             Explicitly force the carp(4) pseudo-device to enter this state.
             Valid states are init, backup, and master.

     vhid n  If the driver is a carp(4) pseudo-device, set the virtual host ID
             to n.  Acceptable values are 1 to 255.

     Taken together, the advbase and advskew indicate how frequently, in sec-
     onds, the host will advertise the fact that it considers itself master of
     the virtual host.  The formula is advbase + (advskew / 256).  If the mas-
     ter does not advertise within three times this interval, this host will
     begin advertising as master.

IEEE 802.11 (WIRELESS DEVICES)
     ifconfig [-M] wireless-interface [[-]bssid bssid] [[-]chan n]
     [[-]nwflag flag] [nwid id] [[-]nwkey key] [[-]powersave]
     [powersavesleep duration] [[-]txpower dBm]

     The options are as follows:

     -M      Show the results of an access point scan.  In Host AP mode, this
             will dump the list of known nodes without scanning.

     bssid bssid
             Set the desired BSSID for IEEE 802.11-based wireless network in-
             terfaces.

     -bssid  Unset the desired BSSID for IEEE 802.11-based wireless network
             interfaces.  The interface will automatically select a BSSID in
             this mode, which is the default.

     chan n  Set the channel (radio frequency) to be used for IEEE
             802.11-based wireless network interfaces from the given channel
             ID n.

     -chan   Unset the desired channel to be used for IEEE 802.11-based wire-
             less network interfaces.  It doesn't affect the channel to be
             created for IBSS or Host AP mode.

     nwflag flag
             Set a specified flag for the wireless network interface.  The
             flag name can be either `hidenwid' or `nobridge'.  The `hidenwid'
             flag will hide the network ID (ESSID) in beacon frames when oper-
             ating in Host AP mode.  It will also prevent responses to probe
             requests with an unspecified network ID.  The `nobridge' flag
             will disable the direct bridging of frames between associated
             nodes when operating in Host AP mode.  Setting this flag will
             block and filter direct inter-station communications.

             Note that the `hidenwid' and `nobridge' options do not provide
             any security.  The hidden network ID will be sent in clear text
             by associating stations and can be easily discovered with tools
             like tcpdump(8) and hostapd(8).

     -nwflag flag
             Remove a specified flag for the wireless network interface.

     nwid id
             Configure network ID for IEEE 802.11-based wireless network in-
             terfaces.  The id can either be any text string up to 32 charac-
             ters in length, or a series of hexadecimal digits up to 64 dig-
             its.  The empty string allows the interface to connect to any
             available access points.  Note that network ID is synonymous with
             Extended Service Set ID (ESSID).

     nwkey key
             Enable WEP encryption for IEEE 802.11-based wireless network in-
             terfaces using the specified key.  The key can either be a
             string, a series of hexadecimal digits (preceded by `0x'), or a
             set of keys of the form ``n:k1,k2,k3,k4'' where `n' specifies
             which of the keys will be used for transmitted packets, and the
             four keys, ``k1'' through ``k4'', are configured as WEP keys.  If
             a set of keys is specified, a comma (`,') within the key must be
             escaped with a backslash.  Note that if multiple keys are used,
             their order must be the same within the network.  For IEEE 802.11
             wireless networks, the length of each key is restricted to 40
             bits, i.e. a 5-character string or 10 hexadecimal digits.  Wave-
             LAN/IEEE Gold and newer Prism cards will also accept a 104-bit
             (13-character) key.

     -nwkey  Disable WEP encryption for IEEE 802.11-based wireless network in-
             terfaces.

     nwkey persist
             Enable WEP encryption for IEEE 802.11-based wireless network in-
             terfaces with the persistent key stored in the network card.

     nwkey persist:key
             Write key to the persistent memory of the network card, and en-
             able WEP encryption for IEEE 802.11-based wireless network inter-
             faces using that key.

     powersave
             Enable 802.11 power saving mode.

     -powersave
             Disable 802.11 power saving mode.

     powersavesleep duration
             Set the receiver sleep duration (in milliseconds) for 802.11 pow-
             er saving mode.

     txpower dBm
             Set the transmit power for IEEE 802.11-based wireless network in-
             terfaces.  The driver will disable any auto level and transmit
             power controls in this mode.

     -txpower
             Disable manual transmit power mode and enable any auto level and
             transmit power controls.

INET6
     ifconfig inet6-interface [[-]anycast] [eui64] [pltime n] [[-]tentative]
     [vltime n]

     The options are as follows:

     anycast
             Set the IPv6 anycast address bit.

     -anycast
             Clear the IPv6 anycast address bit.

     eui64   Fill the interface index (the lowermost 64th bit of an IPv6
             address) automatically.

     pltime n
             Set preferred lifetime for the address.

     tentative
             Set the IPv6 tentative address bit.

     -tentative
             Clear the IPv6 tentative address bit.

     vltime n
             Set valid lifetime for the address.

INTERFACE GROUPS
     ifconfig -g group-name [[-]carpdemote [number]]

     The options are as follows:

     -g group-name
             Specify the group.

     carpdemote [number]
             Increase carp(4) demote count for given interface group by
             number.  If number is omitted, it is increased by 1.

     -carpdemote [number]
             Decrease carp(4) demote count for given interface group by
             number.  If number is omitted, it is decreased by 1.

PFSYNC
     ifconfig pfsync-interface [maxupd n] [[-]syncdev iface]
     [[-]syncpeer peer_address]

     The options are as follows:

     maxupd n
             If the driver is a pfsync(4) pseudo-device, indicate the maximum
             number of updates for a single state which can be collapsed into
             one.  This is an 8-bit number; the default value is 128.

     syncdev iface
             If the driver is a pfsync(4) pseudo-device, use the specified in-
             terface to send and receive pfsync state synchronisation mes-
             sages.

     -syncdev
             If the driver is a pfsync(4) pseudo-device, stop sending pfsync
             state synchronisation messages over the network.

     syncpeer peer_address
             If the driver is a pfsync(4) pseudo-device, make the pfsync link
             point-to-point rather than using multicast to broadcast the state
             synchronisation messages.  The peer_address is the IP address of
             the other host taking part in the pfsync cluster.  With this op-
             tion, pfsync(4) traffic can be protected using ipsec(4).

     -syncpeer
             If the driver is a pfsync(4) pseudo-device, broadcast the packets
             using multicast.

PPPOE
     ifconfig pppoe-interface [authkey key] [authname name] [authproto proto]
     [[-]peerflag flag] [peerkey key] [peername name] [peerproto proto]
     [[-]pppoeac access-concentrator] [pppoedev parent-interface]
     [[-]pppoesvc service]

     pppoe(4) uses the sppp(4) "generic" SPPP framework.  Any options not de-
     scribed in the section immediately following are described in the SPPP
     section, below.  The options are as follows:

     pppoeac access-concentrator
             Set the name of the access-concentrator for the pppoe(4) inter-
             face.

     -pppoeac
             Clear a previously set access-concentrator name.

     pppoedev parent-interface
             Set the name of the interface through which pppoe(4) packets will
             be transmitted and received.

     pppoesvc service
             Set the service name of the pppoe(4) interface.

     -pppoesvc
             Clear a previously set service name.

SPPP (PPP LINK CONTROL PROTOCOL)
     ifconfig sppp-interface [authkey key] [authname name] [authproto proto]
     [[-]peerflag flag] [peerkey key] [peername name] [peerproto proto]

     The options are as follows:

     authkey key
             Set the client key or password for the PPP authentication proto-
             col.

     authname name
             Set the client name for the PPP authentication protocol.

     authproto proto
             Set the PPP authentication protocol on the specified interface
             acting as a client.  The protocol name can be either `chap',
             `pap', or `none'.  In the latter case, authentication will be
             turned off.

     peerflag flag
             Set a specified PPP flag for the remote authenticator.  The flag
             name can be either `callin' or `norechallenge'.  The `callin'
             flag will require the remote peer to authenticate only when he's
             calling in, but not when the peer is called by the local client.
             This is required for some peers that do not implement the authen-
             tication protocols symmetrically.  The `norechallenge' flag is
             only meaningful with the CHAP protocol to not re-challenge once
             the initial CHAP handshake has been successful.  This is used to
             work around broken peer implementations that can't grok being re-
             challenged once the connection is up.

     -peerflag flag
             Remove a specified PPP flag for the remote authenticator.

     peerkey key
             Set the authenticator key or password for the PPP authentication
             protocol.

     peername name
             Set the authenticator name for the PPP authentication protocol.

     peerproto proto
             Set the PPP authentication protocol on the specified interface
             acting as an authenticator.  The protocol name can be either
             `chap', `pap', or `none'.  In the latter case, authentication
             will be turned off.

TRUNK
     ifconfig trunk-interface [[-]trunkport child-iface] [trunkproto proto]

     The options are as follows:

     trunkport child-iface
             If the driver is a trunk(4) pseudo-device, add the child-iface as
             a trunk port.

     -trunkport child-iface
             If the driver is a trunk(4) pseudo-device, remove the trunk port
             child-iface.

     trunkproto proto
             If the driver is a trunk(4) pseudo-device, set the trunk proto-
             col.  Refer to the interface's driver-specific man page for a
             complete list of the available protocols, or use the following
             for a listing of choices:

                   $ ifconfig -m interface

TUNNEL
     ifconfig tunnel-interface [deletetunnel src_address dest_address]
     [tunnel src_address dest_address]

     The options are as follows:

     deletetunnel src_address dest_address
             Remove the source and destination tunnel addresses.

     tunnel src_address dest_address
             Set the source and destination tunnel addresses on a tunnel in-
             terface, including gif(4).  Packets routed to this interface will
             be encapsulated in IPv4 or IPv6, depending on the source and des-
             tination address families.  Both addresses must be of the same
             family.

VLAN
     ifconfig vlan-interface [vlan vlan-tag] [[-]vlandev parent-interface]
     [vlanprio vlan-priority]

     The options are as follows:

     vlan vlan_tag
             If the interface is a vlan(4) pseudo-interface, set the vlan tag
             value to vlan_tag.  This value is a 12-bit number which is used
             to create an 802.1Q vlan header for packets sent from the vlan
             interface.  Note that vlan and vlandev must both be set at the
             same time.

     vlandev parent-interface
             If the interface is a vlan(4) pseudo-device, associate physical
             interface iface with it.  Packets transmitted through the vlan
             interface will be diverted to the specified physical interface
             iface with 802.1Q vlan encapsulation.  Packets with 802.1Q encap-
             sulation received by the parent interface with the correct vlan
             tag will be diverted to the associated vlan pseudo-interface.
             The vlan interface is assigned a copy of the parent interface's
             flags and the parent's Ethernet address.  vlandev and vlan must
             both be set at the same time.  If the vlan interface already has
             a physical interface associated with it, this command will fail.
             To change the association to another physical interface, the ex-
             isting association must be cleared first.

             Note: if the link0 flag is set on the vlan interface, the vlan
             pseudo-interface's behavior changes; link0 tells the vlan inter-
             face that the parent interface supports insertion and extraction
             of vlan tags on its own (usually in firmware) and that it should
             pass packets to and from the parent unaltered.

     -vlandev
             If the driver is a vlan(4) pseudo-device, disassociate the physi-
             cal interface from it.  This breaks the link between the vlan in-
             terface and its parent, clears its vlan tag, flags, and link ad-
             dress, and shuts the interface down.

     vlanprio vlan-priority
             If the interface is a vlan(4) pseudo-interface, set the vlan pri-
             ority value to vlan-priority.  This value is a 3-bit number which
             is used to create an 802.1Q vlan header for packets sent from the
             vlan interface.

EXAMPLES
     Assign the inet(3) address of 192.168.1.10 with a network mask of
     255.255.255.0 to interface fxp0:

           # ifconfig fxp0 inet 192.168.1.10 netmask 255.255.255.0

     Assign the ipx(3) address of 12625920 specified in decimal to interface
     fxp0:

           # ifconfig fxp0 ipx 12625920

     Assign the AppleTalk network 39108 and server node 128 with a network
     range of 39107-39109 to interface fxp0 on a phase 2 AppleTalk network:

           # ifconfig fxp0 atalk 39108.128 range 39107-39109 phase 2

     Configure the xl0 interface to use 10baseT:

           # ifconfig xl0 media 10baseT

     Configure the xl0 interface to use 100baseTX, full duplex:

           # ifconfig xl0 media 100baseTX mediaopt full-duplex

     Label the em0 interface as an uplink:

           # ifconfig em0 description "Uplink to Gigabit Switch 2"

     Configure the vlan0 interface for IP address 192.168.254.1, vlan tag 4,
     and vlan parent device fxp0:

           # ifconfig vlan0 192.168.254.1 vlan 4 vlandev fxp0

     Configure the carp0 interface for IP address 192.168.10.1, virtual host
     ID 1, attached to the vlan0 interface:

           # ifconfig carp0 vhid 1 carpdev vlan0 192.168.10.1

     Create the gif1 network interface:

           # ifconfig gif1 create

     Destroy the gif1 network interface:

           # ifconfig gif1 destroy

     Create and configure the trunk0 interface for IP address 192.168.23.1,
     with the em0 and em1 trunk port interfaces:

           # ifconfig trunk0 create 192.168.23.1 trunkport em0 trunkport em1

DIAGNOSTICS
     Messages indicating the specified interface does not exist, the requested
     address is unknown, or the user is not privileged and tried to alter an
     interface's configuration.

SEE ALSO
     netstat(1), inet(3), ipx(3), arp(4), bridge(4), carp(4), gif(4), gre(4),
     ifmedia(4), inet(4), lo(4), netintro(4), pfsync(4), ppp(4), pppoe(4),
     sl(4), sppp(4), trunk(4), tun(4), vlan(4), hostname.if(5), hosts(5),
     networks(5), brconfig(8), rc(8), routed(8)

HISTORY
     The ifconfig command appeared in 4.2BSD.

OpenBSD 4.0                    September 3, 1998                            11
