Readers should not try to follow instructions directly from the Handbook:Parts namespace (which is THIS page!). The sections displayed below are used as a skeleton for transcluding information into the computer architecture specific handbooks and are therefore lacking critical information.
Please visit the Handbook list to read instructions for a relevant computer architecture.
Netifrc scripts now support 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.
# 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"
We provide two interface handlers presently: ifconfig and iproute2. Only one of these is needed 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.
# To prefer ifconfig over iproute2 if both are installed as openrc prefers # to use iproute2 then modules="ifconfig"
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 the user is using.
config_eth0="192.168.0.2/24" config_eth0="192.168.0.2 netmask 255.255.255.0" # We can also specify broadcast 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, the user just has to tell each client to use DHCP and it sets up the network all by itself. Of course, the user may have to configure a connection to a wireless AP, PPPoE, or other aspects before the DHCP service can be used.
DHCP can be provided by dhclient or dhcpcd. Each DHCP module has its pros and cons - here is a quick run down:
|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, specify which one to use - otherwise dhcpcd is used by default (if it is installed).
To send specific options to the DHCP module, use
module_eth0="..." (change module to the DHCP module being used - i.e. 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:
- Releases the IP address for re-use.
- Don't overwrite /etc/resolv.conf
- Don't overwrite /etc/ntp.conf
- Don't overwrite /etc/yp.conf
# 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.
# 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:
emerge --ask net-dialup/ppp
Second, create the PPP net script and the net script for the Ethernet interface to be used by PPP:
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.
config_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.
# 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 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 the system doesn't connect directly to the Internet and all other computers use APIPA.
# Try DHCP first - if that fails then fallback to APIPA config_eth0="dhcp" fallback_eth0="apipa" # Just use APIPA config_eth0="apipa"
Bonding is used to increase network bandwidth or to improve resiliency in face of hardware failures. If a system has two network cards going to the same network, then the administrator can bond them together so the 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 the local copy of /usr/src/linux/Documentation/networking/bonding.txt.
First, clear the configuration of the participating interfaces:
config_eth0="null" config_eth1="null" config_eth2="null"
Next, define the bonding between the interfaces:
slaves_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 runlevels, create a net.bond0 one and add that one to the correct runlevel.
Bridging (802.1d support)
Bridging is used to join networks together. For example, a system 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. It is possible to create a bridge to join the two interfaces together.
# 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
1as seen in the example above.
It is possible to change the MAC address of the interfaces through the network configuration file too.
# 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 does not require any additional software to be installed as the interface handler can do it.
# For GRE tunnels iptunnel_vpn0="mode gre remote 126.96.36.199 key 0xffffffff ttl 255" # For IPIP tunnels iptunnel_vpn0="mode ipip remote 188.8.131.52 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 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:
Next, configure the interface 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:
vlan1_name="vlan1" vlan1_ingress="2:6 3:5" eth0_vlan1_egress="1:2"
For using some VLAN setups, consult the variable name documentation.