From Gentoo Wiki
Jump to: navigation, search



Netifrc is the default network setup methodology provided with Gentoo in the stage3 tarball, so its available in every install. Netifrc and its optional dependencies can do anything a network admin needs to do with a network. This page describes how to bring up networking using netifrc on a fairly simple system behind a typical domestic router.

Only IPv4 is described here. IPv6 works too.

Users needing the advanced features of netifrc should read /usr/share/doc/netifrc-<version>/net.example.bz2 which is a fully commented example netifrc configuration file.

The Network 'Stack'

In Linux, networking, like so many other things, is arranged like the layers of a cake, the cake is called a stack. When a system is put together the admin chooses the layers in the cake to suit the use case at hand. This makes it easy to add new things as the interfaces between the layers is fixed.

In the cake analogy netifrc is the icing that makes the cake useful. The other layers are all essential but will ned be described here.

Sanity Checking

ip link - does the interface exist

Before netifrc can work, all the other layers of the cake need to be in place, so a few checks are in order

root #ip link
 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 pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 00:e0:4c:69:15:09 brd ff:ff:ff:ff:ff:ff
 3: sit0@NONE: <NOARP> mtu 1480 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/sit brd

must show your real network interface.

Here three interfaces are listed. lo, eth0 and sit0:

  • lo, the loopback interface, is not a real interface.
  • eth0 is a real wired interface.
  • sit0 is an IPv6 over IPv4 tunnel endpoint and is not a real interface.

This page will use eth0 as a wired interface name and wlan0 for a wireless interface. Substitute the name of your interface(s).

Review dmesg

Some network interfaces can appear in the ip link output but still not be working, because they need firmware to be loaded. This is more likely to happen with WiFi than wired interfaces.

root #dmesg | less

Check for firmware loading errors associated with network interfaces and fix them before proceeding. The example below is for the Intel iwlwifi WiFi driver.

CODE dmesg output example
[    1.434197] iwlwifi 0000:02:00.0: Direct firmware load for iwlwifi-2030-6.ucode failed with error -2
[    1.435521] iwlwifi 0000:02:00.0: request for firmware file 'iwlwifi-2030-6.ucode' failed.
[    1.444479] iwlwifi 0000:02:00.0: Direct firmware load for iwlwifi-2030-5.ucode failed with error -2
[    1.512125] iwlwifi 0000:02:00.0: request for firmware file 'iwlwifi-2030-5.ucode' failed.
[    1.512127] iwlwifi 0000:02:00.0: no suitable firmware found!

In this state it will not work.

Address firmware loading problems before proceeding.



This is the netifrc configuration file. No default settings are provided but netifrc defaults to using dhcpcd. If dhcpcd is not installed, the busybox provided udhcpcd will be used.

This means that an empty or non existent /etc/conf.d/net file works for most wired interface users.


Controls the network service behaviour. This file is only of interest to users with more than one interface, where they may not all always be used. Its well commented.


WiFi users will need to install wpa_supplicant and configure /etc/wpa_supplicant/wpa_supplicant.conf

The alternative, wireless-tools is strongly discouraged as it will not support WPA2 wireless encryption.

wpa_supplicant.conf is not a part of netifrc so is not discussed here.


Files of the form /etc/init.d/net.<if_name> must be created by the system admin for each interface that is to be started. They must be symbolic links to /etc/init.d/net.lo and not renamed copies of /etc/init.d/net.lo. This ensures that updates to /etc/init.d/net.lo are also applied to all the other /etc/init.d/net.<if_name> files too.

root #ln -s /etc/init.d/net.lo /etc/init.d/net.eth0

creates the entry for the eth0 interface.

Starting an Interface


root #/etc/init.d/net.eth0 start

Will start the eth0 interface manually, using dhcpcd to obtain all the settings from a dhcp server, (the router). This should just work for most wired interface users.

At Boot

root #rc-update add net.eth0 default

Will start eth0 when the system enters the default runlevel. Networking must not be added to any earlier runlevel.

Static Addressing and Static Routes

Router Setup May be Required to Avoid IP Addresses Being Allocated Twice

There are several ways to perform (or appear to perform) static IP address assignment.

  • bind a MAC address to an IP Address in the router.
  • reserve a range of IP Addresses for static allocation in the router.

The former is entirely router side.

The latter is a required first step for manually assigning settings to an interface. See your router manual. Many routers default to settings of IP address, broadcast and all the addresses in between allocated to dhcp.

There are thus no IPs that can be safely statically allocated without running the risk of an IP address being allocated both statically and dynamically. That doesn't work and its difficult to diagnose.

Adjust the router to restrict the IP range used for dhcp and make a note of the IP range left for static allocation. The router will use its share of the IP address space and static setups can use its share without the risk of an IP address being allocated twice.

Get this right and check it. It may be months or years before it happens and things don't work.


Its possible to mix and match static and dynamic settings with as fine a degree of control as is required. The fine grained control needs cooperation from the router and many domestic routers are defective in that regard.

The following /etc/conf.d/net file allocates the IP address to eth0 and sets the default route via eth0 and the IP address This is the address of the next 'hop' towards the internet.

FILE /etc/conf.d/net
config_eth0=" brd"
routes_eth0="default via"
No matter how many interfaces are fitted, there can be at most a single default route


/etc/resolv.conf is normally populated by dhcpcd but for a static setup, it needs to be done manually.

FILE /etc/resolv.conf
nameserver IP of ISP nameserver 1
nameserver IP of ISP nameserver 2

This file is not a part of netifrc but it is required for network name resolution. Without it, works but will not. The internet works with the numbers but people don't. Nameservers are the internet equivelent of phone books.

nameserver points to the router. It almost certainly runs a caching nameserver, so its consulted first.

Paranoid users can use any public nameserver in place of the ISP nameservers.


Wireless interfaces are similar to wired but there are some extra steps to establish the radio link before the normal wired tools can be applied.

The extra steps are related to association and authentication with a Wireless Access Point. wpa_supplicant performs these steps. It is invoked by netifrc with an entry in /etc/conf.d/net

FILE /etc/conf.d/net
# extra steps

# static wifi
config_wlan0=" brd"
routes_wlan0="default via"

# for dhcp, but dhcp is the default  

External USB Networking Dongles

Users with External USB Networking Dongles, regardless of being wired or wifi, will find that the interface name is dependent on the USB port the dongle is connected to. This is a side effect of udevs 'persistent interface naming'.

Persistent interface naming can be disabled for all interfaces by adding the kernel boot parameter net.ifnames=0 to the kernel line in the boot loader.