Gentoo Logo

Disclaimer : This handbook has been replaced by a newer version and is not maintained anymore.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

2. Advanced Configuration


2.a. Advanced Configuration

The config_eth0 variable is the heart of an interface configuration. It's a high level instruction list for configuring the interface (eth0 in this case). Each command in the instruction list is performed sequentially. The interface is deemed OK if at least one command works.

Here's a list of built-in instructions.

Command Description
null Do nothing
noop If the interface is up and there is an address then abort configuration successfully
an IPv4 or IPv6 address Add the address to the interface
dhcp, adsl or apipa (or a custom command from a 3rd party module) Run the module which provides the command. For example dhcp will run a module that provides DHCP which can be one of either dhcpcd, dhclient or pump.

If a command fails, you can specify a fallback command. The fallback has to match the config structure exactly.

You can chain these commands together. Here are some real world examples.

Code Listing 1.1: Configuration examples

# Adding three IPv4 addresses

# Adding an IPv4 address and two IPv6 addresses

# Keep our kernel assigned address, unless the interface goes
# down so assign another via DHCP. If DHCP fails then add a
# static address determined by APIPA

Note: When using the ifconfig module and adding more than one address, interface aliases are created for each extra address. So with the above two examples you will get interfaces eth0, eth0:1 and eth0:2. You cannot do anything special with these interfaces as the kernel and other programs will just treat eth0:1 and eth0:2 as eth0.

Important: The fallback order is important! If we did not specify the null option then the apipa command would only be run if the noop command failed.

Note: APIPA and DHCP are discussed later.

2.b. Network Dependencies

Init scripts in /etc/init.d can depend on a specific network interface or just net. All network interfaces in Gentoo's init system provide what is called net.

If, in /etc/rc.conf, rc_depend_strict="YES" is set, then all network interfaces that provide net must be active before a dependency on "net" is assumed to be met. In other words, if you have a net.eth0 and net.eth1 and an init script depends on "net", then both must be enabled.

On the other hand, if rc_depend_strict="NO" is set, then the "net" dependency is marked as resolved the moment at least one network interface is brought up.

But what about net.br0 depending on net.eth0 and net.eth1? net.eth1 may be a wireless or PPP device that needs configuration before it can be added to the bridge. This cannot be done in /etc/init.d/net.br0 as that's a symbolic link to net.lo.

The answer is defining an rc_need_ setting in /etc/conf.d/net.

Code Listing 2.1: net.br0 dependency in /etc/conf.d/net

rc_need_br0="net.eth0 net.eth1"

That alone, however, is not sufficient. Gentoo's networking init scripts use a virtual dependency called net to inform the system when networking is available. Clearly, in the above case, networking should only be marked as available when net.br0 is up, not when the others are. So we need to tell that in /etc/conf.d/net as well:

Code Listing 2.2: Updating virtual dependencies and provisions for networking


For a more detailed discussion about dependency, consult the section Writing Init Scripts in the Gentoo Handbook. More information about /etc/rc.conf is available as comments within that file.

2.c. Variable names and values

Variable names are dynamic. They normally follow the structure of variable_${interface|mac|essid|apmac}. For example, the variable dhcpcd_eth0 holds the value for dhcpcd options for eth0 and dhcpcd_essid holds the value for dhcpcd options when any interface connects to the ESSID "essid".

However, there is no hard and fast rule that states interface names must be ethx. In fact, many wireless interfaces have names like wlanx, rax as well as ethx. Also, some user defined interfaces such as bridges can be given any name, such as foo. To make life more interesting, wireless Access Points can have names with non alpha-numeric characters in them - this is important because you can configure networking parameters per ESSID.

The downside of all this is that Gentoo uses bash variables for networking - and bash cannot use anything outside of English alpha-numerics. To get around this limitation we change every character that is not an English alpha-numeric into a _ character.

Another downside of bash is the content of variables - some characters need to be escaped. This can be achived by placing the \ character in front of the character that needs to be escaped. The following list of characters needs to be escaped in this way: ", ' and \.

In this example we use wireless ESSID as they can contain the widest scope of characters. We shall use the ESSID My "\ NET:

Code Listing 3.1: variable name example

(This does work, but the domain is invalid)
dns_domain_My____NET="My \"\\ NET"

(The above sets the dns domain to My "\ NET when a wireless card
connects to an AP whose ESSID is My "\ NET)

2.d. Network Interface Naming

How It Works

Network interface names are not chosen arbitrarily: the Linux kernel and the device manager (most systems have udev as their device manager although others are available as well) choose the interface name through a fixed set of rules.

When an interface card is detected on a system, the Linux kernel gathers the necessary data about this card. This includes:

  1. the onboard (on the interface itself) registered name of the network card, which is later seen through the ID_NET_NAME_ONBOARD parameter;
  2. the slot in which the network card is plugged in, which is later seen through the ID_NET_NAME_SLOT parameter;
  3. the path through which the network card device can be accessed, which is later seen through the ID_NET_NAME_PATH parameter;
  4. the (vendor-provided) MAC address of the card, which is later seen through the ID_NET_NAME_MAC parameter;

Based on this information, the device manager decides how to name the interface on the system. By default, it uses the first hit of the first three parameters above (ID_NET_NAME_ONBOARD, _SLOT or _PATH). For instance, if ID_NET_NAME_ONBOARD is found and set to eno1, then the interface will be called eno1.

If you know your interface name, you can see the values of the provided parameters using udevadm:

Code Listing 4.1: Reading the network interface card information

# udevadm test-builtin net_id /sys/class/net/enp3s0 2>/dev/null
ID_OUI_FROM_DATABASE=Quanta Computer Inc.

As the first (and actually only) hit of the top three parameters is the ID_NET_NAME_PATH one, its value is used as the interface name. If none of the parameters is found, then the system reverts back to the kernel-provided naming (eth0, eth1, etc.)

Using the Old-style Kernel Naming

Before this change, network interface cards were named by the Linux kernel itself, depending on the order that drivers are loaded (amongst other, possibly more obscure reasons). This behavior can still be enabled by setting the net.ifnames=0 boot option in the boot loader.

Using your Own Names

The entire idea behind the change in naming is not to confuse people, but to make changing the names easier. Suppose you have two interfaces that are otherwise called eth0 and eth1. One is meant to access the network through a wire, the other one is for wireless access. With the support for interface naming, you can have these called lan0 (wired) and wifi0 (wireless - it is best to avoid using the previously well-known names like eth* and wlan* as those can still collide with your suggested names).

All you need to do is to find out what the parameters are for the cards and then use this information to set up your own naming rule:

Code Listing 4.2: Setting the lan0 name for the current eth0 interface

# udevadm test-builtin net_id /sys/class/net/eth0 2>/dev/null
ID_OUI_FROM_DATABASE=Quanta Computer Inc.

# vim /etc/udev/rules.d/70-net-name-use-custom.rules
# First one uses MAC information, and 70- number to be before other net rules
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="c8:0a:a9:42:9d:76", NAME="lan0"

# vim /etc/udev/rules.d/76-net-name-use-custom.rules
# Second one uses ID_NET_NAME_PATH information, and 76- number to be between
# 75-net-*.rules and 80-net-*.rules
SUBSYSTEM=="net", ACTION=="add", ENV{ID_NET_NAME_PATH}=="enp3s0", NAME="wifi0"

Because the rules are triggered before the default one (rules are triggered in alphanumerical order, so 70 comes before 80) the names provided in the rule file will be used instead of the default ones. The number granted to the file should be between 76 and 79 (the environment variables are defined by a rule start starts with 75 and the fallback naming is done in a rule numbered 80).

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated August 17, 2014

Summary: Here we learn about how the configuration works - you need to know this before we learn about modular networking.

Sven Vermeulen

Roy Marples

Daniel Robbins

Chris Houser

Jerry Alexandratos

Joshua Saddler

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Tobias Scherbaum

Xavier Neys

Shyam Mani

Grant Goodyear

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Lars Weiler

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.