ifconfig 1 administrator commands nosh ifconfig network interface configuration tool ifconfig options-and-flags 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. 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 TerminalCapabilities3 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. 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 % 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. On FreeBSD, where lo4 is a cloning interface: # ifconfig lo1 create # ifconfig -l -d lo1 # ifconfig lo1 destroy # ifconfig -l -d # 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 are inet4, inet6, and link. 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 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 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 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. # 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 # 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. There are two ifconfig8 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 ifconfig8 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. Jonathan de Boyne Pollard