Gentoo Logo

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

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

3. Modular Networking


3.a. Network Modules

We now support modular networking scripts, which means we can easily add support for new interface types and configuration modules while keeping compatibility with existing ones.

Modules load by default if the package they need is installed. If you specify a module here that doesn't have its package installed then you get an error stating which package you need to install. Ideally, you only use the modules setting when you have two or more packages installed that supply the same service and you need to prefer one over the other.

Note: All settings discussed here are stored in /etc/conf.d/net unless otherwise specified.

Code Listing 1.1: Module preference

# Prefer ifconfig over iproute2

# You can also specify other modules for an interface
# In this case we prefer pump over dhcpcd

# You can also specify which modules not to use - for example you may be
# using a supplicant or linux-wlan-ng to control wireless configuration but
# you still want to configure network settings per ESSID associated with.

3.b. Interface Handlers

We provide two interface handlers presently: ifconfig and iproute2. You need one of these to do any kind of network configuration.

ifconfig is installed by default (the net-tools package is part of the system profile). iproute2 is a more powerful and flexible package, but it's not included by default.

Code Listing 2.1: To install iproute2

# emerge sys-apps/iproute2

# To prefer ifconfig over iproute2 if both are installed as openrc prefers
# to use iproute2 then

As both ifconfig and iproute2 do very similar things we allow their basic configuration to work with each other. For example both the below code snippet work regardless of which module you are using.

Code Listing 2.2: ifconfig and iproute2 examples

config_eth0=" netmask"

# We can also specify broadcast
config_eth0=" brd"
config_eth0=" netmask broadcast"

3.c. DHCP

DHCP is a means of obtaining network information (IP address, DNS servers, Gateway, etc) from a DHCP server. This means that if there is a DHCP server running on the network, you just have to tell each client to use DHCP and it sets up the network all by itself. Of course, you will have to configure for other things like wireless, PPP or other things if required before you can use DHCP.

DHCP can be provided by dhclient, dhcpcd, or pump. Each DHCP module has its pros and cons - here's a quick run down.

DHCP Module Package Pros Cons
dhclient net-misc/dhcp Made by ISC, the same people who make the BIND DNS software. Very configurable Configuration is overly complex, software is quite bloated, cannot get NTP servers from DHCP, does not send hostname by default
dhcpcd net-misc/dhcpcd Long time Gentoo default, no reliance on outside tools, actively developed by Gentoo Can be slow at times, does not yet daemonize when lease is infinite
pump net-misc/pump Lightweight, no reliance on outside tools No longer maintained upstream, unreliable, especially over modems, cannot get NIS servers from DHCP

If you have more than one DHCP client installed, you need to specify which one to use - otherwise we default to dhcpcd if available.

To send specific options to the DHCP module, use module_eth0="..." (change module to the DHCP module you're using - i.e. dhcpcd_eth0).

We try and make DHCP relatively agnostic - as such we support the following commands using the dhcp_eth0 variable. The default is not to set any of them:

  • release - releases the IP address for re-use
  • nodns - don't overwrite /etc/resolv.conf
  • nontp - don't overwrite /etc/ntp.conf
  • nonis - don't overwrite /etc/yp.conf

Code Listing 3.1: Sample DHCP configuration in /etc/conf.d/net

# Only needed if you have more than one DHCP module installed

dhcpcd_eth0="-t 10" # Timeout after 10 seconds
dhcp_eth0="release nodns nontp nonis" # Only get an address

Note: dhcpcd and pump send the current hostname to the DHCP server by default so you don't need to specify this anymore.

3.d. ADSL with PPPoE/PPPoA

First we need to install the ADSL software.

Code Listing 4.1: Install the ppp package

# emerge net-dialup/ppp

Second, create the PPP net script and the net script for the ethernet interface to be used by PPP:

Code Listing 4.2: Creating the PPP and ethernet scripts

# ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0
# ln -s /etc/init.d/net.lo /etc/init.d/net.eth0

Be sure to set rc_depend_strict to "YES" in /etc/rc.conf.

Now we need to configure /etc/conf.d/net.

Code Listing 4.3: A basic PPPoE setup

config_eth0=null (Specify your ethernet interface)
link_ppp0="eth0" (Specify your ethernet interface)
holdoff 3
child-timeout 60
lcp-echo-interval 15
lcp-echo-failure 3
noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"


You can also set your password in /etc/ppp/pap-secrets.

Code Listing 4.4: Sample /etc/ppp/pap-secrets

# The * is important
"username"  *  "password"

If you use PPPoE with a USB modem you'll need to emerge br2684ctl. Please read /usr/portage/net-dialup/speedtouch-usb/files/README for information on how to properly configure it.

Important: Please carefully read the section on ADSL and PPP in /usr/share/doc/netifrc-*/net.example.bz2. It contains many more detailed explanations of all the settings your particular PPP setup will likely need.

3.e. APIPA (Automatic Private IP Addressing)

APIPA tries to find a free address in the range by arping a random address in that range on the interface. If no reply is found then we assign that address to the interface.

This is only useful for LANs where there is no DHCP server and you don't connect directly to the internet and all other computers use APIPA.

For APIPA support, emerge net-misc/iputils or net-analyzer/arping.

Code Listing 5.1: APIPA configuration in /etc/conf.d/net

# Try DHCP first - if that fails then fallback to APIPA

# Just use APIPA

3.f. Bonding

For link bonding/trunking emerge net-misc/ifenslave.

Bonding is used to increase network bandwidth or to improve resiliency in face of hardware failures. If you have two network cards going to the same network, you can bond them together so your applications see just one interface but they really use both network cards.

There are many ways to configure bonding. Some of them, such as the 802.3ad LACP mode, require support and additional configuration of the network switch. For a reference of the individual options, please refer to your copy of /usr/src/linux/Documentation/networking/bonding.txt.

First, clear the configuration of the participating interfaces:

Code Listing 6.1: Clearing interface configuration in /etc/conf.d/net


Next, define the bonding between the interfaces:

Code Listing 6.2: Define the bonding

slaves_bond0="eth0 eth1 eth2"
# Pick a correct mode and additional configuration options which suit your needs

Remove the net.eth* services from the runlevels, create a net.bond0 one and add that one to the correct runlevel.

3.g. Bridging (802.1d support)

For bridging support emerge net-misc/bridge-utils.

Bridging is used to join networks together. For example, you may have a server that connects to the internet via an ADSL modem and a wireless access card to enable other computers to connect to the internet via the ADSL modem. You could create a bridge to join the two interfaces together.

Code Listing 7.1: Bridge configuration in /etc/conf.d/net

# Configure the bridge - "man brctl" for more details
brctl_br0="setfd 0
sethello 2
stp on"

# To add ports to bridge br0
bridge_br0="eth0 eth1"

# You need to configure the ports to null values so dhcp does not get started

# Finally give the bridge an address - you could use DHCP as well

# Depend on eth0 and eth1 as they may require extra configuration
rc_need_br0="net.eth0 net.eth1"

Important: For using some bridge setups, you may need to consult the variable name documentation.

3.h. MAC Address

If you need to, you can change the MAC address of your interfaces through the network configuration file too.

Code Listing 8.1: MAC Address change example

# To set the MAC address of the interface

# To randomize the last 3 bytes only

# To randomize between the same physical type of connection (e.g. fibre,
# copper, wireless) , all vendors

# To randomize between any physical type of connection (e.g. fibre, copper,
# wireless) , all vendors

# Full randomization - WARNING: some MAC addresses generated by this may
# NOT act as expected

3.i. Tunnelling

You don't need to emerge anything for tunnelling as the interface handler can do it for you.

Code Listing 9.1: Tunnelling configuration in /etc/conf.d/net

# For GRE tunnels
iptunnel_vpn0="mode gre remote key 0xffffffff ttl 255"

# For IPIP tunnels
iptunnel_vpn0="mode ipip remote ttl 255"

# To configure the interface
config_vpn0=" peer"

3.j. VLAN (802.1q support)

For VLAN support, make sure that sys-apps/iproute2 is installed and ensure that iproute2 is used as configuration module rather than ifconfig.

Virtual LAN is a group of network devices that behave as if they were connected to a single network segment - even though they may not be. VLAN members can only see members of the same VLAN even though they may share the same physical network.

To configure VLANs, first specify the VLAN numbers in /etc/conf.d/net like so:

Code Listing 10.1: Specifying VLAN numbers

vlans_eth0="1 2"

Next, configure the interface for each VLAN:

Code Listing 10.2: Interface configuration for each VLAN

config_eth0_1=" netmask"
routes_eth0_1="default via"

config_eth0_2=" netmask"
routes_eth0_2="default via"

VLAN-specific configurations are handled by vconfig like so:

Code Listing 10.3: Configuring the VLANs

vlan1_ingress="2:6 3:5"

Important: For using some VLAN setups, you may need to consult the variable name documentation.

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


View all

Page updated September 25, 2014

Summary: Gentoo provides you flexible networking - here you are told about choosing different DHCP clients, setting up bonding, bridging, VLANs and more.

Sven Vermeulen

Roy Marples

Daniel Robbins

Chris Houser

Jerry Alexandratos

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

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.