From Gentoo Wiki
Jump to: navigation, search

netifrc is a collection of modules created to configure and manage network interfaces via individual, per-interface scripts.

In Gentoo netifrc comes installed as part of the system profile and is available in the stage3 tarballs on all architectures. New users beware: netifrc is powerful and convenient, but using it requires knowledge of the exact system needs; because of its modular approach it requires additional packages to be installed for what many users would consider "basic functionality" for home users.

The netifrc package can be uninstalled or simply left unused in favor of using another network manager.


USE flags

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:

root #emerge --ask net-misc/netifrc



Service scripts located in the /etc/init.d/ directory.


The systemd service which calls a wrapper script. See the sections below for more information.


net.lo is a generic script used as the target (base) for symlinks. It contains logic necessary to determine what interfaces to start or stop given the appropriate command from the init system.
This file is not created by default; it is created by the system administrator. Its should configuration information for each network interface to be managed by netifrc (details on content can be found below).

Basic examples

FILE /etc/conf.d/netExample DHCP configuration
# Note: DHCP is the default behavior if the /etc/conf.d/net
Static address (CIDR notation)
FILE /etc/conf.d/netExample static IP using CIDR
# For a static IP using CIDR notation
routes_eth0="default via"
# The is provided here to show that multiple DNS servers entries can be added for a single interface.
Static address (netmask notation)
FILE /etc/conf.d/netExample static IP using netmask
# For a static IP using netmask notation
config_eth0=" netmask"
routes_eth0="default via"

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.

First, the ip command will list all available interfaces when given the link action. If the -s option is passed to ip, before the action, activity statistics will also display to show connectivity:

user $ip -s link
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    RX: bytes  packets  errors  dropped overrun mcast
    0          0        0       0       0       0
    TX: bytes  packets  errors  dropped carrier collsns
    0          0        0       0       0       0
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
    RX: bytes  packets  errors  dropped overrun mcast
    236957926  2697517  0       344244  0       2595885
    TX: bytes  packets  errors  dropped carrier collsns
    9532180    91898    0       0       0       0
3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN mode DEFAULT group default qlen 1
    link/sit brd
    RX: bytes  packets  errors  dropped overrun mcast
    0          0        0       0       0       0
    TX: bytes  packets  errors  dropped carrier collsns
    0          0        0       0       0       0

Next, 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:

user $ifconfig -a

For more information on ifconfig see the man page locally (man ifconfig) or online.

Alternately, 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:

user $dmesg | grep -i "network interface"

For more information on the use of dmesg see the man page locally (man dmesg) or online.

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.

Maximum transmission unit size

To set a specific MTU size for an interface edit the /etc/conf.d/net file like below:

FILE /etc/conf.d/netMTU size

Adding interfaces


Creating symlinks

Provided in the net-misc/netifrc package is a parent script called net.lo which is installed to /etc/init.d/net.lo. This parent script should be symlinked to create additional scripts for each network interface to be configured. For example, to create a script for a network interface called eth0, run the following command:

root #ln -s /etc/init.d/net.lo /etc/init.d/net.<interface_name>

Replace <interface_name> with eth0 or whatever the interface is named.

Curly braces and commas can be used to speed up the process when dealing with multiple interfaces:
root #ln -s /etc/init.d/net.{lo,<interface_name>}

<interface_name> in the example commands above is the appropriate name for this system's network interface. Depending on the system, a number of interface names may be used including: eno1, enp2s0, wlan0, ethernet0, wireless0, etc. Continue creating links for as many interfaces as needed. A system can have more than one interface connected to more than one network if the hardware is available.

Configuration of the interfaces is handled in the /etc/conf.d/net file. A default (empty or missing) /etc/conf.d/net will automatically use DHCP to configure any network interface(s) started by net.* scripts.

Enable at boot

Running the rc-update is the final step in the configuration process. Add each interface to the system's init process. Normally interfaces are added to the default runlevel:

root #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.


The net@.service unit is provided. To enable and start this unit:

root #systemctl --now enable net@<interface_name>.service

Removing interfaces

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:


root #rc-update del net.<interface_name> default


root #systemctl disable net@<interface_name>.service

Priority of network interfaces

When 2 or more network interfaces are up, to set their priority, as example for preferred internet access on wlan0:

FILE /etc/conf.d/net
# Routing priority


Link event detection

If an Ethernet cable plugged in after the bootup process occurred the network interfaces will 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 init 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:

root #emerge --ask sys-apps/ifplugd

Once the install is complete network interfaces should be refreshed automatically whenever the system detects a link change event.

For more information please read netifrc documentation at Gentoo's GitWeb site or locally in /usr/share/doc/netifrc-<version_number>/net.example.bz2. Search "Cable in/out detection".

See also

External resources