Handbook:X86/Networking/Modular
Network modules
Netifrc supports modular networking scripts, which means support for new interface types and configuration modules can easily be added while keeping compatibility with existing ones.
Modules load by default if the package they need is installed. If users specify a module here that doesn't have its package installed then they get an error stating which package they need to install. Ideally, the modules setting is only used when two or more packages are installed that supply the same service and one needs to be preferred over the other.
All settings discussed here are stored in /etc/conf.d/net unless otherwise specified.
/etc/conf.d/netModule definitions# Prefer ifconfig over iproute2
# modules="ifconfig"
# You can also specify other modules for an interface
# In this case we prefer dhclient over dhcpcd
modules_eth0="dhclient"
# 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.
modules="!iwconfig"
Interface handlers
We provide two interface handlers: ifconfig and iproute2. You need one of these to do any kind of network configuration.
Both are installed by default as part of the system profile. iproute2 is the more powerful and flexible package. ifconfig and net-tools should not be used anymore for networking configuration setups.
As iproute2 and ifconfig do very similar things, we allow their basic configuration to work with each other. For example, the below configuration works regardless of the module used.
/etc/conf.d/netExample configurationconfig_eth0="192.168.0.2/24"
config_eth0="192.168.0.2 netmask 255.255.255.0"
DHCP
DHCP is a means of obtaining an IP address, together with other network information (DNS server(s), gateway, etc.) from a server. With a DHCP server running on a network, the user just has to tell each device to obtain configuration information via DHCP, which is then used to configure the device automatically. Of course, this requires a network connection (e.g. via a wireless access point, PPPoE, etc.).
DHCP can be provided by dhclient or dhcpcd. Each DHCP module has its pros and cons - here is 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. Can be used to provide DHCPv4 or DHCPv6. | Configuration is overly complex, software is quite bloated, cannot get NTP servers from DHCP, does not send hostname by default. No longer maintained upstream. |
| dhcpcd | net-misc/dhcpcd | Long time Gentoo default, no reliance on outside tools, actively developed by Gentoo. Provides DHCPv4 and DHCPv6 at the same time. | Can be slow at times, does not yet daemonize when lease is infinite. |
If more than one DHCP client is installed, it is possible to specify which client to use by setting the "modules" variable, e.g. modules="dhcpcd". Otherwise, if dhcpcd is installed, it's used by default.
To send specific options to the DHCP module, use module_eth0="...", where module is the name of the DHCP module being used - for example, "dhcpcd_eth0".
We try to 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
/etc/conf.d/netSample DHCP (v4) configuration# Only needed if more than one DHCP module is installed
modules="dhcpcd"
config_eth0="dhcp"
dhcpcd_eth0="-t 10" # Timeout after 10 seconds
dhcp_eth0="release nodns nontp nonis" # Only get an address
dhcpcd sends the current hostname to the DHCP server by default so this no longer needs to be specified.
/etc/conf.d/netSample DHCPv6 configuration# Only needed if more than one DHCP module is installed
modules="dhclient"
config_eth0="dhcpv6"
# To use both DHCPv4 and DHCPv6 on a dual-stack network, remove the above line and uncomment the following lines
#config_eth0="dhcp
#dhcpv6"
# To pass runtime arguments to dhclient for DHCPv6
dhclientv6_eth0="-t 10" # Timeout after 10 seconds
# Set generic DHCPv6 options
dhcpv6_eth0="release nodns nontp nonis nogateway nosendhost"
ADSL with PPPoE/PPPoA
First install the ADSL software:
root #emerge --ask net-dialup/pppSecond, create the PPP net script and the net script for the Ethernet interface to be used by PPP:
root #ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0
root #ln -s /etc/init.d/net.lo /etc/init.d/net.eth0Be sure to set rc_depend_strict to YES in /etc/rc.conf.
Now we need to configure /etc/conf.d/net.
/etc/conf.d/netA basic PPPoE setupconfig_eth0=null (Specify the ethernet interface)
config_ppp0="ppp"
link_ppp0="eth0" (Specify the ethernet interface)
plugins_ppp0="pppoe"
username_ppp0='user'
password_ppp0='password'
pppd_ppp0="
noauth
defaultroute
usepeerdns
holdoff 3
child-timeout 60
lcp-echo-interval 15
lcp-echo-failure 3
noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"
rc_net_ppp0_need="net.eth0"
It is also possible to set the password in /etc/ppp/pap-secrets.
/etc/ppp/pap-secretsSample pap-secrets# The * is important
"username" * "password"
If PPPoE is used with a USB modem then make sure to emerge br2684ctl. Please read /var/db/repos/gentoo/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 any particular PPP setup will likely need.
APIPA (Automatic Private IP Addressing)
APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by using arping to ping a random address in that range on the interface. If no reply is received, that address is assigned to the interface.
This is only useful for LANs where:
- there is no DHCP server;
- the system doesn't connect directly to the Internet; and
- all other computers use APIPA.
For APIPA support, emerge net-misc/iputils with the arping USE flag or net-analyzer/arping.
/etc/conf.d/netAPIPA configuration# Try DHCP first - if that fails then fallback to APIPA
config_eth0="dhcp"
fallback_eth0="apipa"
# Just use APIPA
config_eth0="apipa"
Bonding
Bonding is used to increase network bandwidth or to improve resiliency in the face of hardware failures. If a system has two network cards going to the same network, they can be bonded: applications will see just one interface, but both network cards will be used.
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 the local copy of /usr/src/linux/Documentation/networking/bonding.txt.
First, clear the configuration of the participating interfaces:
/etc/conf.d/netClearing interface configurationconfig_eth0="null"
config_eth1="null"
config_eth2="null"
Next, define the bonding between the interfaces:
/etc/conf.d/netDefine the bondingslaves_bond0="eth0 eth1 eth2"
config_bond0="192.168.100.4/24"
# Pick a correct mode and additional configuration options which suit your needs
mode_bond0="balance-alb"
Remove the net.eth* services from the relevant runlevel, create a net.bond0 service, and add that service to the appropriate runlevel.
Bridging (802.1d support)
Bridging is used to join networks together. For example, a network may have a server that connects to the Internet via an ADSL modem, and also has a wireless adapter to allow other devices on the network to access the Internet via that modem. It is possible to create a bridge to join the two interfaces together.
/etc/conf.d/netBridge configuration# Configure the bridge - "man brctl" for more details
bridge_forward_delay_br0=0
bridge_hello_time_br0=200
bridge_stp_state_br0=1
# 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
config_eth0="null"
config_eth1="null"
# Finally give the bridge an address - you could use DHCP as well
config_br0="192.168.0.1/24"
# Depend on eth0 and eth1 as they may require extra configuration
rc_net_br0_need="net.eth0 net.eth1"
For using some bridge setups, consult the variable name documentation.
When bridging using IPv6, SLAAC requires STP to be set to
1 as seen in the example above.MAC address
It is possible to change the MAC address of the interfaces through the network configuration file too.
/etc/conf.d/netMAC Address change example# To set the MAC address of the interface
mac_eth0="00:11:22:33:44:55"
# To randomize the last 3 bytes only
mac_eth0="random-ending"
# To randomize between the same physical type of connection (e.g. fibre,
# copper, wireless) , all vendors
mac_eth0="random-samekind"
# To randomize between any physical type of connection (e.g. fibre, copper,
# wireless) , all vendors
mac_eth0="random-anykind"
# Full randomization - WARNING: some MAC addresses generated by this may
# NOT act as expected
mac_eth0="random-full"
Tunneling
Tunneling does not require any additional software to be installed as the interface handler can do it.
/etc/conf.d/netTunneling configuration# For GRE tunnels
iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
# For IPIP tunnels
iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
# To configure the interface
config_vpn0="192.168.0.2 peer 192.168.1.1"
VLAN (802.1q support)
For VLAN support, make sure that sys-apps/iproute2 is installed, and ensure that iproute2 is used as the configuration module (rather than ifconfig).
A VLAN, 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. Members of a VLAN can only see other members of the same VLAN, even when they share the same physical network.
To configure VLANs, first specify the VLAN numbers in /etc/conf.d/net like so:
/etc/conf.d/netSpecifying VLAN numbersvlans_eth0="1 2"
Next, configure the interface for each VLAN:
/etc/conf.d/netInterface configuration for each VLANconfig_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:
/etc/conf.d/netConfiguring the VLANsvlan1_name="vlan1"
vlan1_ingress="2:6 3:5"
eth0_vlan1_egress="1:2"
For using some VLAN setups, consult the variable name documentation.