ifconfig

Configure network interface parameters

Syntax:

ifconfig interface address_family [address [dest_address]]
         [parameters]
ifconfig [-hLmvz] interface [protocol_family]
ifconfig -a [-bdhLmsuvz] [protocol_family]
ifconfig -l [-b] [-d] [-u] [-s]
ifconfig -s interface
ifconfig -C

Runs on:

Neutrino

Options:

-a

Display information about all of the interfaces in the system. You can use the -d, -u, -b, and -s options with this option to limit this display.

-b

List only the broadcast interfaces.

-C

List all of the interface cloners available on the system, with no additional information. This option is mutually exclusive with all other options and commands.

-d

List only the interfaces that are down.

-h

If you use this option in conjunction with -v, ifconfig prints the byte statistics are in human-readable format.

-L

Display the address lifetime for IPv6 addresses, as a time offset string.

-l

List all available interfaces on the system, with no additional information. This option is mutually exclusive with all other options and commands, except for -b, -d, -s, -u.

-m

Display all of the supported media for all of the interfaces in the system (used in conjunction with -a).

If you specify the -m option before an interface name, ifconfig displays all of the supported media for the specified interface.

-s

If you specify the -a option, the -s option makes ifconfig list only the interfaces that are connected.

If you specify the -s option for a specific interface, ifconfig queries the interface for its media status. If the interface supports reporting media status, and it reports that it doesn't appear to be connected to a network, ifconfig exits with status of 1 (false); otherwise, it exits with zero (true). Not all interface drivers support media status reporting.

-u

List only the interfaces which are up.

-v

Print statistics on packets sent and received on the given interface. You can use the -h in conjunction with -v to display the byte statistics in human-readable format.

-z

Similar to the -v flag, except that it zeros the interface's input and output statistics after printing them.

interface

The name of the interface to configure. This is a string of the form name unit (e.g. en1)

address

Either a hostname present in the /etc/hosts database, or a DARPA-Internet address expressed in the standard Internet “dot notation.”

For the Xerox Network Systems family, addresses are in 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.

For the ISO family, addresses are specified as a long hexadecimal string, as in the Xerox family. However, two consecutive dots imply a zero byte, and the dots are optional, if you wish to (carefully) count out long strings of digits in network byte order.

address_family

The address family that affects the interpretation of the remaining parameters. Specifying an address family is recommended since an interface can receive transmissions in differing protocols with different naming schemes. Address or protocol families currently supported are inet, inet6, atalk, iso, and ns.

dest_address

Address of the correspondent on the other end of a point-to-point link (for pppx interfaces only).

parameters

See the “Parameters” section below.

protocol_family

Report only the details specific to this protocol family.

Description:

The ifconfig utility is used to assign an address and/or configure parameters for a network interface. This utility must be run at boot time to define the network address of each interface present on a machine; it may also be run later on to redefine an interface's address or to configure other interface parameters.

When no optional parameters are specified, ifconfig displays the current configuration for a network interface. If you specify a protocol family, ifconfig reports only the details specific to that protocol family.

---

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

---

Parameters

You may set the following parameters with the ifconfig utility, if the driver supports them. The output from ifconfig for an interface lists the supported parameters.

alias

Establish an additional network address for this interface. This is useful when someone changes network address of an interface, or when someone wishes to accept packets addressed to the old interface.

-alias

Remove the additional network address for this interface.

anycast

(inet6 only) Set the IPv6 anycast address bit.

-anycast

(inet6 only) Clear the IPv6 anycast address bit.

apbridge

(IEEE 802.11 devices only) When operating as an access point, pass packets between wireless clients directly (the default).

-apbridge

(IEEE 802.11 devices only) When operating as an access point, pass packets through the system so that they can be forwarded using some other mechanism. Disabling the internal bridging is useful when traffic is to be processed with packet filtering.

arp

Enable the use of the Address Resolution Protocol in mapping between network-level addresses and link-level addresses (default). This is implemented to do mapping between DARPA Internet addresses and Ethernet addresses.

-arp

Disable the use of the Address Resolution Protocol.

broadcast mask

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

bssid bssid

(IEEE 802.11 devices only) Set the desired BSSID for IEEE 802.11-based wireless network interfaces.

-bssid

(IEEE 802.11 devices only) 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 chan

(IEEE 802.11 devices only) Select the channel (radio frequency) to use for IEEE 802.11-based wireless network interfaces.

-chan

(IEEE 802.11 devices only) Unset the desired channel to to be used for IEEE 802.11-based wireless network interfaces. It doesn't affect the channel to be created for IBSS or hostap mode.

chanlist channels

Set the channels to use when scanning for access points, neighbors in an IBSS network, or looking for unoccupied channels when operating as an access point.

Specify the set of channels as a comma-seperated list, with each element in the list representing either a single channel number of a range of the form a-b. Channel numbers must be in the range 1 through 255 and be permissible according to the operating characteristics of the device.

create

Create the specified network pseudo-device.

debug

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

-debug

Disable driver-dependent debugging code.

delete

Remove a specified network address. You should use this parameter if you have incorrectly specified an alias, or you will no longer use an alias. In the event that you have incorrectly set an NS address which has the side effect of specifying the host portion, you must respecify the host portion while removing all NS addresses. Note that this parameter doesn't work for IPv6 addresses. If you need to delete IPv6 addresses, use -alias with an explicit IPv6 address.

deletetunnel

Unconfigure the physical source and destination address for IP tunnel interfaces previously configured with tunnel.

deprecated

(inet6 only) Set the IPv6 deprecated address bit.

-deprecated

(inet6 only) Clear the IPv6 deprecated address bit.

destroy

Destroy the specified network pseudo-device.

dest_address

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

down

Mark an interface as being down. When an interface is marked down, the system doesn't attempt to transmit messages through that interface. If possible, the interface is reset to disable reception as well. This action doesn't automatically disable routes using the interface.

eui64

(inet6 only) Fill the interface index (the lowermost 64 bits of an IPv6 address) automatically.

hidessid

(IEEE 802.11 devices only) When operating as an access point, don't broadcast the SSID in beacon frames or respond to probe request frames unless they're directed to the access point (i.e. they include its SSID). By default, the SSID is included in beacon frames, and undirected probe request frames are answered.

-hidessid

(IEEE 802.11 devices only) When operating as an access point, broadcast the SSID in beacon frames and answer and respond to undirected probe request frames (default).

instance minst

Set the media instance to minst. This is useful for devices that have multiple physical layer interfaces (PHYs). Setting the instance on such devices may not be strictly required by the network interface driver because the driver may take care of this automatically; see the driver's documentation for more information.

ip4csum, ip4csum-rx, ip4csum-tx

Enable hardware-assisted IPv4 header checksums, if they're supported. You can restrict this action to either the Rx or Tx direction, if the hardware permits it.

-ip4csum, -ip4csum-rx, -ip4csum-tx

Disable hardware-assisted IPv4 header checksums.

ipdst

Specify an Internet host that's willing to receive IP packets encapsulating NS packets bound for a remote network. An apparent point-to-point link is constructed, and the address specified is taken as the NS address and network of the destination. IP encapsulation of CLNP packets is done differently.

link mac [active|delete]

Dynamically modify the specified interface's MAC addresses. If you don't specify active or delete, ifconfig adds the given MAC address. The active command activates the address, and the delete command removes it.

link[0-2]

Enable special processing of the link level of the interface. These three options are interface-specific in actual effect, but you use them in general to select special modes of operation. An example of this is to select the connector type for some ethernet cards. For more information, see the documentation for the specific driver.

-link[0-2]

Disable special processing at the link level with the specified interface.

media type

Set the media type of the interface to type. Some interfaces support the mutually exclusive use of one of several different physical media connectors. For example, a 10 Mb/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 active connector to the AUI port. Setting it to 10baseT or UTP would activate twisted pair. Refer to the interfaces' driver-specific documentation for a complete list of the available types.

mediaopt opts

Set the specified media options on the interface. The opts argument is a comma-delimited list of options to apply to the interface. For information about the available options, see the documentation for each driver.

-mediaopt opts

Disable the specified media options on the interface.

metric n

Set the routing metric of the interface to n. The default is 0. The routing metric is used by the routing protocol (routed). Higher metrics have the effect of making a route less favorable; metrics are counted as additional hops to the destination network or host.

mode mode

If the driver supports the media selection system, set the specified operating mode on the interface to mode. For IEEE 802.11 wireless interfaces that support multiple operating modes, this directive is used to select between 802.11a (11a), 802.11b (11b), and 802.11g (11g) operating modes.

mtu n

Set the maximum transmission unit of the interface to n. Most interfaces don't support this parameter.

netmask mask

(inet, inet6, and ISO) Specify how much of the address to reserve 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. You can specify the mask as a single hexadecimal number with a leading 0x, with a dot-notation Internet address, or with a pseudo-network name listed in the network table, networks.

The mask contains ones for the bit positions in the 32-bit address that are to be used for the network and subnet parts, and zeroes for the host part. The mask should contain at least the standard network portion, and the subnet field should be contiguous with the network portion.

For INET and INET6 addresses, you can also give the netmask with slash-notation after the address (e.g. 192.168.17.3/24).

nsellength n

(ISO only) This specifies a trailing number of bytes for a received NSAP used for local identification, the remaining leading part of which is taken to be the NET (Network Entity Title). The default value is 1, which is conformant to US GOSIP. When an ISO address is set in an ifconfig command, it's really the NSAP that's being specified. For example, in US GOSIP, 20 hex digits should be specified in the ISO NSAP to be assigned to the interface. There is some evidence that a number different from 1 may be useful for AFI 37 type addresses.

nwid id

A synonym for ssid.

nwkey key

(IEEE 802.11 devices only) Enable WEP encryption for IEEE 802.11-based wireless network interfaces with the key. The key can either be a string, a series of hexadecimal digits preceded by 0x, or a set of keys in the form n:k1,k2,k3,k4, where n specifies which of keys will be used for all transmitted packets, and four keys, k1 through k4, are configured as WEP keys. Note that the order must be matched within same network if you use multiple keys. For IEEE 802.11 wireless network, the length of each key is restricted to 40 bits, i.e. a 5-character string or 10 hexadecimal digits, while the WaveLAN/IEEE Gold cards accept the 104 bits (13 characters) key.

nwkey persist

(IEEE 802.11 devices only) Enable WEP encryption for IEEE 802.11-based wireless network interfaces with the persistent key written in the network card.

nwkey persist:key

(IEEE 802.11 devices only) Write the key to the persistent memory of the network card, and enable WEP encryption for IEEE 802.11-based wireless network interfaces with the key.

-nwkey

(IEEE 802.11 devices only) Disable WEP encryption for IEEE 802.11-based wireless network interfaces.

pltime n

(inet6 only) Set the preferred lifetime for the address, in seconds.

powersave

(IEEE 802.11 devices only) Enable 802.11 power-saving mode.

-powersave

(IEEE 802.11 devices only) Disable 802.11 power-saving mode.

powersavesleep duration

(IEEE 802.11 devices only) Set the receiver sleep duration, in milliseconds, for the 802.11 power-saving mode.

prefixlen n

(inet and inet6 only) Similar to netmask, but you can specify the length of the prefix.

ssid id

(IEEE 802.11 devices only) Configure the Service Set Identifier (also known as the network name) for IEEE 802.11-based wireless network interfaces. The id can either be any text string up to 32 characters in length, or a series of up to 64 hexadecimal digits preceded by 0x. Setting id to the empty string allows the interface to connect to any available access point.

tcp4csum, tcp4csum-rx, tcp4csum-tx

Enable hardware-assisted TCP/IPv4 checksums, if they're supported. You can restrict this action to either the Rx or Tx direction, if the hardware permits it.

-tcp4csum, -tcp4csum-rx, -tcp4csum-tx

Disable hardware-assisted TCP/IPv4 checksums.

tcp6csum, tcp6csum-rx, tcp6csum-tx

Enable hardware-assisted TCP/IPv6 checksums, if they're supported. You can restrict this action to either the Rx or Tx direction, if the hardware permits it.

-tcp6csum, -tcp6csum-rx, -tcp6csum-tx

Disable hardware-assisted TCP/IPv6 checksums.

tentative

(inet6 only) Set the IPv6 tentative address bit.

-tentative

(inet6 only) Clear the IPv6 tentative address bit.

tso4

Enable hardware-assisted TCP/IPv4 segmentation on interfaces that support it.

-tso4

Disable hardware-assisted TCP/IPv4 segmentation on interfaces that support it.

tunnel src_addr[,src_port] dest_addr[,dest_port]

(IP tunnel devices only) Configure the physical source and destination address for IP tunnel interfaces, including gif. The arguments, src_addr and dest_addr are interpreted as the outer source and destination for the encapsulating IPv4/IPv6 header.

On a gre interface in UDP mode, the arguments src_port and dest_port are interpreted as the outer source and destination port for the encapsulating UDP header.

udp4csum, udp4csum-rx, udp4csum-tx

Enable hardware-assisted UDP4 checksums, if they're supported. You can restrict this action to either the Rx or Tx direction, if the hardware permits it.

-udp4csum, -udp4csum-rx, -udp4csum-tx

Disable hardware-assisted UDP4 checksums.

udp6csum, udp6csum-rx, udp6csum-tx

Enable hardware-assisted UDP6 checksums, if they're supported. You can restrict this action to either the Rx or Tx direction, if the hardware permits it.

-udp6csum, -udp6csum-rx, -udp6csum-tx

Disable hardware-assisted UDP6 checksums.

up

Mark an interface as being up. You can use this to enable an interface after an ifconfig down command. By default, an interface is marked as “up” the first time ifconfig is run to assign the interface an address. If the interface was reset when previously marked down, the hardware is reinitialized.

vlan tag

If the interface is a vlan pseudo-interface, set the VLAN tag to tag. This is a 16-bit number which is used to create an 802.1Q VLAN header for packets sent from the vlan interface. Note that you must set vlan and vlanif at the same time.

vlanif iface

If the interface is a vlan pseudo-interface, associate the 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 encapsulation received by the physical interface with the correct VLAN tag will be diverted to the associated vlan pseudo-interface.

The VLAN interface is assigned a copy of the physical interface's flags and Ethernet address. 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 existing association must be cleared first.

Note that you must set vlan and vlanif at the same time.

vltime n

(inet6 only) Set the valid lifetime for the address.

The following parameters are specific to IEEE 802.11 wireless interfaces:

list active

Display the list of channels available for use, taking into account any restrictions set with the chanlist directive. See the description of list chan for more information.

list caps

Display the adaptor's capabilities, including the operating modes supported.

list chan

Display the list of channels available for use. Channels are shown with their IEEE channel number, equivalent frequency, and usage modes. Channels identified as “11g” are also usable in “11b” mode. Channels identified as “11a Turbo” may be used only for Atheros' Static Turbo mode (specified with mediaopt turbo). Channels marked with a * have a regulatory constraint that they be passively scanned. This means a station isn't permitted to transmit on the channel until it identifies the channel as being used for 802.11 communication, typically by hearing a beacon frame from an access point operating on the channel. You can also use list freq to request this information.

list mac

Display the current MAC Access Control List state. Each address is prefixed with a character that indicates the current policy applied to it:

This character:	Indicates:
+	The address is allowed access.
-	The address is denied access.
*	The address is present, but the current policy is open (so the ACL isn't consulted).

list scan

Display the access points and/or ad hoc neighbors located in the vicinity. You can use the -v option to display long SSIDs. This information may be updated automatically by the adaptor and/or with a scan request. You can also use list ap to request this information.

list sta

When operating as an access point, display the stations that are currently associated. When operating in ad hoc mode, display stations identified as neighbors in the IBSS. Capabilities advertised by the stations are described under the scan request. Depending on the capabilities of the stations the following flags can be included in the output:

A

Authorized. Indicates that the station is permitted to send/receive data frames.

E

Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates.

P

Power Save. Indicates that the station is operating in power-saving mode.

scan

Initiate a scan of neighboring stations, wait for it to complete, and display all stations found. Only the superuser can initiate a scan. Depending on the capabilities of the APs, the following flags can be included in the output:

E

Extended Service Set (ESS). Indicates that the station is part of an infrastructure network (in contrast to an IBSS/ad hoc network).

I

IBSS/ad hoc network. Indicates that the station is part of an ad hoc network (in contrast to an ESS network).

P

Privacy. Data confidentiality is required for all data frames exchanged within the BSS. This means that this BSS requires the station to use cryptographic means such as WEP, TKIP, or AES-CCMP to encrypt and decrypt data frames being exchanged with others.

S

Short Preamble. Indicates that the network is using short preambles (defined in 802.11b High Rate/DSSS PHY). A short preamble uses a 56-bit sync field, in contrast to a 128-bit field used in long preamble mode.

s

The network is using a short slot time.

You can use the list scan request to show recent scan results without initiating a new scan. You can use the -v option to prevent the shortening of long SSIDs.

Diagnostics

Depending on the error, the utility may display messages indicating:

• the specified interface doesn't exist
• the requested address is unknown
• the user isn't privileged and tried to alter an interface's configuration

Examples:

Enable hardware-assisted TCP/IPv6 checksums on an interface:

ifconfig wm0 tcp6csum

See also:

/etc/autoconnect, /etc/hosts netmanager, netstat, phlip, routed

gif, gre, vlan in the NetBSD documentation at http://www.netbsd.org/docs/

QNX Neutrino Core Networking User's Guide