netifrc is Gentoo's default framework for configuring and managing network interfaces on systems running OpenRC. It comes installed as part of the system profile and is available in the stage3 tarballs on all architectures.
netifrc is powerful and convenient, but new users be aware: Using it requires knowledge of the exact system needs. Because of its modular approach it may require additional packages to be installed for what many users may consider "basic functionality" for home use.
The netifrc package can be uninstalled or simply left unused in favor of using another network manager.
For some simple network setups, such as cabled Ethernet to a home router, no network configuration may be necessary, further than installing a dhcp server.
The OpenRC package has the
netifrc USE flag, pulling in the package and enabling Gentoo's network stack (net.* scripts).
The netifrc modules come in standard stage3 tarballs so they should be already installed on the system. In the case they have been removed, they can be re-installed via:
emerge --ask net-misc/netifrc
- is the central configuration file. Everything goes in here. It contains all options for all network interfaces managed by netifrc (details on content can be found below) including physical interfaces, bridges, wireless etc. Netifrc does not create the file by default: It is created by the system administrator either manually or through configuration tools during system installation, such as net-setup.
Within netifrc, each network interface is:
- Configured in the /etc/conf.d/net file.
- Controlled through it's own /etc/init.d/net.<interface_name> service script file, except for some dynamic interfaces such as Veth.
The config procedure involves both editing /etc/conf.d/net and creating the corresponding service script for each interface.
Netifrc provides a comprehensive set of features and configuration options. The complete guide is found on the netifrc documentation at Gentoo's GitWeb site.
Although it's not necessary to explicitly configure it, here's an example to make use of DHCP on an interface.
# Note: DHCP is the default behavior if /etc/conf.d/net is empty or missing config_eth0="dhcp"
DHCP with WPA Supplicant
If WiFi is used, a module is needed for performing network authentication, such as wpa_supplicant.
# Note: This depends on wpa_supplicant being installed modules_wlan0="wpa_supplicant" config_wlan0="dhcp"
Static address (CIDR notation)
If no DHCP is used, a static address can be configured.
# For a static IP using CIDR notation config_eth0="192.168.0.7/24" routes_eth0="default via 192.168.0.1" # The 22.214.171.124 is provided here to show that multiple DNS servers entries can be added for a single interface. dns_servers_eth0="192.168.0.1 126.96.36.199"
Use CIDR instead of the older Netmask notation today. For IPv6 or a dual stack IPv4/IPv6 setup it's mandatory.
Static address (netmask notation)
This is a different notation for the same static address, route and DNS configuration.
# For a static IP using netmask notation config_eth0="192.168.0.7 netmask 255.255.255.0" routes_eth0="default via 192.168.0.1" dns_servers_eth0="192.168.0.1 188.8.131.52"
A default (empty or missing) /etc/conf.d/net will automatically use DHCP to configure any network interface(s) started by net.* scripts.
Network bridge, multiple interfaces, IPv6
When migrating a bridge from brctl to iproute, see the Netifrc/Brctl Migration article.
As stated above, each network interface configured in /etc/conf.d/net needs its own service script located in the /etc/init.d/ directory:
- is the parent service script provided by the package. It contains all the logic to control all interfaces managed by netifrc with the init system. It's meant to be the target for creating interface symlinks only. Do not edit.
- /etc/init.d/net.xyz (example)
- user created symlink to /etc/init.d/net.lo for controlling interface
xyz. For each interface controlled by netifrc, there must be a symlink.
Determine interface names
The first step in configuring netifrc is to get a list of the network interfaces present on the system. This is possible a couple different ways:
Alternative 1: The ip command will list all available interfaces when given the link action.
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000 link/ether 9a:02:79:45:ce:d2 brd ff:ff:ff:ff:ff:ff 3: eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000 link/ether ac:1f:6b:ad:43:23 brd ff:ff:ff:ff:ff:ff ...
The above command output is a cropped example. On a typical system, more interfaces will be present. Be aware that most of them are no physical interfaces, but virtual ones used for a variety of purposes.
In this example,
eth1 are physical ("real") network interfaces. They can be used for network connections outside the machine. In the description fields it can be seen that
eth0 is up and running (active) while
eth1 is down (not active).
Depending on the system, many interface names may be listed including: eno1, enp2s0, wlan0, ethernet0, wireless0, etc. A system can have more than one interface connected to more than one network if the hardware is available.
Alternative 2: the ifconfig command can be used to get a comprehensive list of available interfaces. It also be an used to detect if there is byte-activity on the interfaces which helps determine connectivity:
For more information on ifconfig see the man page locally (man ifconfig) or online.
Alternative 3: if dmesg is installed, a list of messages should be generated each time the system boots. Although the above method is better in practice, this approach can also be used to determine available network interfaces:
dmesg | grep -i "network interface"
For more information on the use of dmesg see the man page locally (man dmesg) or online.
Alternative 4: List known devices in /sys/class/net:
eth0 eth1 lo sit0
If network interfaces cannot be discovered using the means above, but the physical system hardware indicates otherwise, it is likely the appropriate kernel drives for the network interface(s) have not been built for the currently running kernel or the system is lacking required firmware for interaction with the interface. Either the kernel will need to be configured to support the NIC driver and recompiled or the firmware will need to be installed; in some cases both changes will need to be performed For more information on how to perform these changes see the kernel configuration article.
Now that the interface name is determined and configuration is done in /etc/conf.d/net, the service script must be created. This is done by creating a symlink to /etc/init.de/net.lo:
ln -s /etc/init.d/net.lo /etc/init.d/net.<interface_name>
<interface_name> with the name of the interface, for example
eth0. Repeat for all interfaces that are configured and need to be started. These include hardware interfaces as well as bridges, tap interfaces etc.
When done with all interfaces, the existence of the script symlinks:
ls /etc/init.d/net.* -l
lrwxrwxrwx 1 root root 6 Oct 10 2019 net.br0 -> net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.eth0 -> net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.eth1 -> net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.enp7s0 -> net.lo -rwxr-xr-x 1 root root 18514 Oct 09 15:37 net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.tap1 -> net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.tap2 -> net.lo lrwxrwxrwx 1 root root 6 Oct 10 2019 net.tap3 -> net.lo
In the example above, service scripts for 1 bridge (br0), 2 ethernet interfaces (eth0, eth1), 1 sfp+ interface (enp7s0) and 3 bridge ports (tap1, tap2, tap3) have been created. Note that net.lo is the only real file and the symlink target of all others.
Bring up / down / restart interfaces
As everything is configured now, interfaces can be managed by netifrc. This example uses the
Start (bring up) an interface:
rc-service net.eth0 start
Stop (bring down) an interface:
rc-service net.eth0 stop
Stopping the primary routing interface will likely break the network connection. Care must be taken especially on remote machines, e.g. on SSH access. Restarting interfaces is usually the better choice.
Restart an interface:
rc-service net.eth0 restart
Enable at boot
Running the rc-update is the final step in the configuration process. Add each interface to the system's init process so they are automatically started when the system boots. Normally interfaces are added to the default runlevel:
rc-update add net.<interface_name> default
Repeat the above command for each interface. A status message should appear showing successful adds to the init process.
Disable at boot
If interfaces are no longer desired to be loaded during the init process they need to be removed from OpenRC or systemd. Run the following command for each interface that should be removed:
rc-update del net.<interface_name> default
This article focuses on OpenRC as Gentoo's default init system. It is however possible run netifrc on systemd but at current, this requires deep knowledge (disable sysv-utils USE on systemd, adjust bootloader etc). For the sake of completeness, there are a couple differences to be documented here for systemd:
- The net@.service unit is provided.
- The systemd service calls a wrapper script (provided by netifrc).
Enable and start this unit on boot:
systemctl --now enable net@<interface_name>.service
Disable this unit:
systemctl disable net@<interface_name>.service
Maximum transmission unit size
To set a specific MTU size for an interface edit the /etc/conf.d/net file like below:
Priority of network interfaces
When 2 or more network interfaces are up, to set their priority, as example for preferred internet access on wlan0:
# Routing priority metric_wlan0="90" metric_eth0="100"
Troubleshooting: Link event detection
If an Ethernet cable is plugged in after the bootup process occurred, the network interfaces may not manually refresh themselves - even when using a DHCP client to manage the connections. A new address will not be assigned until the interface is manually refreshed by running the associated service script.
Two packages are available to aid in refreshing the network interface(s) during link events:
The sys-apps/ifplugd package appears to be more maintained and is the recommended choice:
emerge --ask sys-apps/ifplugd
Once the install is complete network interfaces should be refreshed automatically whenever the system detects a link change event.
Setting ethtool options
Sometimes it might be needed to set specific ethtool options. This can be done via /etc/conf.d/net. For example, to disable TCP segmentation offload, generic segmentation offload, and generic receive offload on network interface eth0:
ethtool_offload_eno1="tso off gro off gso off"
Netifrc itself has no man page. The full configuration options are found on the netifrc documentation at Gentoo's GitWeb site or locally in /usr/share/doc/netifrc-<version_number>/net.example.bz2. Search "
Cable in/out detection".
- Networking (AMD64 Handbook) - The Gentoo Handbook explains netifrc scripts in a high level of detail.
- Eudev: Classic interface naming - How to keep classic naming for network interfaces instead of udev's 'predictable' interface naming.
- Network management using DHCPCD — explains how to use dhcpcd for complete network stack management.
- Brctl Migration — outlines details necessary to migrate a netifrc-based bridge setup from brctl to iproute.