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.
All settings discussed here are stored in /etc/conf.d/net unless
Code Listing 1.1: Module preference
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
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="192.168.0.2 netmask 255.255.255.0"
config_eth0="192.168.0.2/24 brd 192.168.0.255"
config_eth0="192.168.0.2 netmask 255.255.255.0 broadcast 192.168.0.255"
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 can be provided by dhclient, dhcpcd, or pump. Each
DHCP module has its pros and cons - here's a quick run down.
Made by ISC, the same people who make the BIND DNS software. Very
Configuration is overly complex, software is quite bloated, cannot get
NTP servers from DHCP, does not send hostname by default
Long time Gentoo default, no reliance on outside tools, actively developed
||Can be slow at times, does not yet daemonize when lease is infinite
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
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
dhcp_eth0="release nodns nontp nonis"
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
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
"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.
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
3.e. APIPA (Automatic Private IP Addressing)
APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 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
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
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"
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
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
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
iptunnel_vpn0="mode gre remote 126.96.36.199 key 0xffffffff ttl 255"
iptunnel_vpn0="mode ipip remote 188.8.131.52 ttl 255"
config_vpn0="192.168.0.2 peer 192.168.1.1"
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
To configure VLANs, first specify the VLAN numbers in
/etc/conf.d/net like so:
Code Listing 10.1: Specifying VLAN numbers
Next, configure the interface for each VLAN:
Code Listing 10.2: Interface configuration for each VLAN
config_eth0_1="172.16.3.1 netmask 255.255.254.0"
routes_eth0_1="default via 172.16.3.254"
config_eth0_2="172.16.2.1 netmask 255.255.254.0"
routes_eth0_2="default via 172.16.2.254"
VLAN-specific configurations are handled by vconfig like so:
Code Listing 10.3: Configuring the VLANs
For using some VLAN setups, you may need to consult the variable name documentation.
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.