ifconfig 1 administrator commands nosh
ifconfig network interface configuration tool
`ifconfig` options-and-flags

## Description

`ifconfig` is a tool for configuring network interfaces. Its primary purpose is to provide a uniform tool across platforms that can be incorporated into services that deal in network device configuration. It only handles link-layer, IP version 4, and IP version 6 configuration.

### Reporting interface configuration

`ifconfig` -u -d --colour -a address-family `ifconfig` -u -d --colour -l address-family `ifconfig` -u -d --colour interface address-family

Invoked in these manners, `ifconfig` displays information about the network interfaces as currently configured. With the -a and -l options it displays information about all network interfaces, otherwise it displays information about the one named interface.

If the standard output is a terminal, `ifconfig` uses whatever it can find via the TerminalCapabilities 3 library to display various parts of the output in different colours, highlighting addresses in different address families in different colours. The --colour command line option tells it to do this unconditionally, even if its standard output is not a terminal.

The address-family command-line option restricts its output to information about only that particular address family, eliminating any interfaces that do not have any addresses in that family. The -u and -d command-line options restrict reporting to only interfaces that are, respectively, up or down.

The -l command-line option causes a short listing that contains only interface names. Otherwise, both interface names and configuration information are displayed. The latter is displayed in a form that is roughly the same as `ifconfig`'s own command line. Each network address is on a separate line, and with a minimal amount of massaging the output could in theory be fed back to `ifconfig` as its command line, one line at a time.

The output prefers to display prefix lengths rather than network masks, and will only fall back to the latter if the network mask is not a true prefix. Network masks, broadcast addresses, and point-to-point addresses are displayed in the same form as addresses. The notation bdaddr is used where an interface has a broadcast/point-to-point address but is not specifically marked as either broadcast or point-to-point. This is generally an erroneous state.

#### Examples

On a system with two Ethernet interfaces and a loopback interface, where only one of the Ethernet interfaces has any IP version 6 addresses, and the other is down:

    % ifconfig -l
    enp14s0 enp15s0 lo
    % ifconfig -l inet6
    enp14s0 lo
    % ifconfig -l -d
    enp15s0
    %

### Interface cloning

`ifconfig` interface create address-family address flags `ifconfig` interface destroy `ifconfig` -C
Not all operating systems support interface cloning. Linux does not, for example.

With the -C option, `ifconfig` displays is a list of all cloners, i.e. interfaces which can be cloned via the create subcommand.

With the create and destroy subcommands, `ifconfig` can be used to create and to destroy instances of cloneable interfaces. For compatibility, flags and one address can also be specified at creation. It is recommended not to do this, however.

It is also recommended to explicitly supply the unit number of the cloned interface, as `ifconfig` provides no means for obtaining the unit number generated by the kernel if the interface to be cloned is unitless.

#### Examples

On FreeBSD, where lo 4 is a cloning interface:

    # ifconfig lo1 create
    # ifconfig -l -d
    lo1
    # ifconfig lo1 destroy
    # ifconfig -l -d
    #

### Reconfiguring existing interfaces

`ifconfig` interface address-family address flags `ifconfig` interface address-family address alias flags `ifconfig` interface address-family address -alias flags

Invoked in these manners, `ifconfig` adds or deletes an address, of the given address family, to or from the given interface; and sets flags on and off. One can change flags without changing addresses, and change addresses without changing flags.

Modern networking is no longer structured around the idea of network interfaces having a single "primary" IP address and zero or more subordinate "alias" addresses. (The syntax of the command that `ifconfig` is compatible with is structured around that old idea.) The first form of the command when supplied an address does the same thing as the second form, rather than overwriting a single primary address. The third form is capable of removing any address, down to an interface having zero IP addresses, rather than only removing alias addresses.

#### Address families

Address families are inet4, inet6, and link.

#### Addresses

Interfaces may, and commonly do, have multiple addresses in the IP address families; and just one address at the link layer. These addresses are specified with three pieces of information, spread across various command-line options:

address addr
address addr/prefixlen

  A literal address in the given address family, specifying the interface address to add/delete. The optional prefixlen is mutually exclusive with the prefixlen and netmask options.

netmask addr
prefixlen prefix

  These are mutually exclusive with a prefixlen in the main address, and specify the network mask to be used, either (old-style) in the form of an address or (new-style) in the form of a numeric prefix length.

  prefixlen is not restricted to just IP version 6.
broadcast addr
dest addr

  These are mutually exclusive with each other, and specify the broadcast or point-to-point address to be used. They will automatically switch on the relevant flag, turning the other flag off. (Setting these flags directly, as actual flags, is not permitted.)

scope number

  This specifies the scope of the address. Neither Linux nor the BSDs document for end-users what the various address scopes actually are.

Commas here are part of how definition lists are rendered in manual pages, and are not part of the command-line syntax.

#### Flags

Flags are set on by specifying the flag name to turn them on. To turn them off, prefix the flag with either - or no. (For flags with negative senses such as noarp this means either nonoarp or -noarp.) The exceptions are eui64, broadcast1, anycast, up, and down, which do not have negative forms.

What flags are supported, apart from a basic common set (up, down, debug, loopback, noarp, allmulti, and promisc) varies from operating system to operating system.

The set of flags also varies by address family, IP version 6 having extra flags, related to neighbourhood discovery and suchlike, that are not applicable to IP version 4. It is thus required to specify address-family when setting flags. For convenience nd6 is a synonym for the IP version 6 address family.

alias has the appearance of a flag, for compatibility, but actually is not.

##### broadcast1

broadcast1 is a flag, but can only be set on. It is mutually exclusive with explicitly setting a broadcast address. It causes a broadcast address to be calculated from the supplied address and netmask, setting all of the host part bits of the address to 1.

##### eui64

eui64 is a flag, but can only be set on. It is only allowed for IP version 6 addresses, and only when the prefix length is 64 or less. It causes the interface to be scanned for any existing link-local IP version 6 addresses, and the lower 64 bits of such an address (if found) to be substituted into the address that is to be added/deleted.

When auto_linklocal is turned on, the kernel automatically adds a link-local IP version 6 address based upon the MAC address, and eui64 thus causes `ifconfig` to propagate the MAC address (converted to EUI-64) into routable IP version 6 addresses with the given prefix.

The privacy-conscious can turn auto_linklocal off, explicitly assign link-local IP version 6 addresses that do not use MAC addresses in their lower 64 bits, and have those employed by eui64 instead. However, the IP version 6 prefix may, by itself, already be enough to uniquely identify a system.

`ifconfig` will propagate whatever the lower 64 bits are, as-is. Passing the MAC address, either alone or in conjunction with a machine-local "salt", through a hash function is insufficient for privacy, and `ifconfig` does not do that. (For an IP version 6 address not to provide strong identification, it must change regularly, in a pattern that cannot be inferred from outwith the system. This is not the case for a hashed value of an unchanging MAC address and an unchanging salt.)

`ifconfig` intentionally makes no attempt to directly employ and convert the MAC address. It is intentionally an error to employ eui64 without either setting auto_linklocal or explicitly providing a link-local IP version 6 address with the desired lower 64 bits.

On some operating systems, with certain address families, the netmask and broadcast/point-to-point addresses are ignored when deleting an address. On others, they must match the values associated with the address to be deleted. For best results across platforms and address families, always supply matching values.

#### Examples

    # ifconfig enp15s0 link up
    # ifconfig enp15s0 inet6 ::3/128 alias
    # ifconfig enp15s0 inet6 2001:db8::/32 eui64 alias
    # ifconfig enp15s0 inet6 2001:db8::/32 eui64 -alias
    # ifconfig enp15s0 inet6 ::3/128 -alias
    # ifconfig enp15s0 link down
    #

## Kernel problems

There are several errors which are caused by the operating system kernel:

- Linux fails, with an "invalid argument" error, if broadcast is used in the IP version 6 address family. It only allows broadcast addresses with IP version 4.

- Linux fails, with an "invalid argument" error, if scope is used with a non-zero scope in the IP version 4 address family. It only allows scopes with IP version 6.

## Compatibility

There are two ifconfig 8 tools available on Linux operating systems, one from GNU inetutils and the other from NET-3 net-tools. They are incompatible with each other, having significantly different syntaxes; they are incompatible with the BSD tool; they have trouble with alias addresses; they have limited or outright missing support for IP version 6; and they are not in fact portable outwith Linux. `ifconfig` is not intended to be compatible with them.

`ifconfig` is, rather, modelled on the FreeBSD ifconfig 8 tool, providing the subset of its functionality that is needed to support cross-platform networking services. However, this is not a slavish imitation. The FreeBSD tool does not, for starters, display interface flags and options in a way that can be fed back on its own command line almost unchanged. The FreeBSD tool makes address-family optional when setting flags. The FreeBSD tool makes -a the default behaviour. The FreeBSD tool has compatibility options for BSD/OS and Solaris. The FreeBSD bizarrely displays network masks in hexdecimal, with the addresses in decimal, but only for IP version 4. And the FreeBSD tool erroneously allows combinations of the mutually exclusive -a, -l, and -C options.

## Author

Jonathan de Boyne Pollard