Funtoo Linux Core Networking

Introduction

Funtoo Core Networking has been enabled in Funtoo stable (funtoo) and unstable (~funtoo) builds -- see Scheduled Change 2009.1

Funtoo Linux has its own core network configuration that differs from upstream network configuration systems used in Gentoo Linux and OpenRC. Despite this difference, Funtoo Linux remains compatible with upstream Gentoo Linux and OpenRC.

In this document, I will explain the unique additions and changes to the Funtoo core network interface configuration system (core-netif), why these changes were made, and how to use this system to configure your network.

In addition, the use of dhcpcd 5.x will be covered for managing network interafaces in a dynamic fashion, and Wi-Fi (IEEE 802.11) configuration and the OpenResolv framework will also be explained.

core-netif License

The Funtoo Core Network Interface Configuration System (core-netif) consists of independently-developed source code that is released under its own distinct licensing terms, and is currently hosted as part of a forked OpenRC tree at http://www.github.com/funtoo/openrc/.

The Funtoo Core Boot Framework is distributed under the following terms:

Copyright 2009-2010 Funtoo Technologies, LLC.

This program is free software; you can redistribute and/or modify it under the terms of the 2-clause BSD license. Alternatively you may (at your option) use any other license that has been publicly approved for use with this program by Funtoo Technologies, LLC. (or its successors, if any.)

At this time (December 2009), no other licenses other than the default license (BSD 2-clause license) have been approved by Funtoo Technologies, LLC for use with this program.

core-netif differences

In Funtoo Linux, the /etc/netif.d directory contains modular network configuration templates

The modular template system allows for simpler, purpose-built network interface configuration scripts to be created, rather than having a monolithic "one size fits all" universal network script as in Gentoo and OpenRC. These lighter-weight network configuration scripts can be more easily read, understood -- and modified if desired. This approach is much more extensible.

In Funtoo Linux, network interface configuration scripts are named netif.* rather than net.*

In Funtoo Linux, /etc/init.d/net is a dummy script that serves a single purpose -- to satisfy dependencies for all initscripts that need net. Funtoo network interface scripts are named /etc/init.d/netif.*.

In Funtoo Linux, network interfaces must be added to your default runlevel to be enabled.

Gentoo Linux has the unfortunate behavior of starting all network interfaces and DHCP clients found in /etc/init.d when something needs net, whether or not you've added these network interfaces or DHCP clients to your current runlevel. This is due to the way the net initscript dependency is implemented, and works against the elegant, modular runlevel design of Gentoo and Funtoo initscripts.

In Funtoo Linux, if you want a network interface to be started in a runlevel, you must manually add it to that runlevel by typing:

# rc-update add netif.eth0 default

This allows different runlevels to have different network interfaces enabled or disabled. In Funtoo Linux, dhcpcd also needs to be added to your current runlevel in order to enable it:

# rc-update add dhcpcd default

In Funtoo Linux, stopping a single network interface does not stop all network-dependent services.

In Gentoo, if you stop net.eth0, all network-dependent services will also be stopped. In Funtoo Linux, by default it is safe to stop or restart netif.eth0 or any other network interface. By default, network-dependent services will keep running.

It is possible to modify this behavior in a very fine-grained way. Say that you need netif.eth0 to be up so that netmount can mount an NFS filesystem. To do this, add the following line to /etc/conf.d/netmount:

rc_need="netif.eth0"

This will cause netmount to start netif.eth0 prior to mounting the remote NFS filesystem, and will cause netmount to be stopped if netif.eth0 is stopped. However, sshd, which listens on all interfaces and does not require a particular network interface to be "up", will remain running even if netif.eth0 is stopped.

If you would want netif.eth0 to start before netmount starts, but don't want the stopping or restarting of netif.eth0 to cause netmount to stop or restart, then you would do this:

rc_use="netif.eth0"

This may not be useful for netmount, which typically needs to maintain persistent network connections, but may be useful for scripts that need to only perform a short burst of network activity, such as one-time NTP time synchronization, or if you would prefer a script like sshd to start after netif.eth0 without a restart of netif.eth0 causing sshd to also restart. The rc_after and rc_before settings can also be used for this purpose.

using core-netif

If you wanted to use the Funtoo core-netif template system for the netif.eth0 interface, you would first create a netif.eth0 symlink to netif.tmpl in the /etc/init.d directory:

# cd /etc/init.d
# ln -s netif.tmpl netif.eth0

Then, choose a template you want to use -- see /etc/netif.d for a complete list of network configuration templates. You will then create a /etc/conf.d/netif.eth0 file and put this at the top of it:

# I will use "/etc/netif.d/interface":
template="interface"
description="my public interface"

Then, you will define required and optional variables for the particular template you are using. Here is a description of all currently-available network templates:

Templates

interface -- this is a standard manually-configured network interface. IP and NM (network mask) are required; GW (gateway), DOM (domain), NS1 (name server 1) and NS2 (name server 2) are optional.

interface-noip -- this is a minimal interface with no configurable parameters. This template is typically used for slave bridge interfaces.

bond -- this is a standard bond interface. SLAVES (slave interfaces, in SLAVES="netif.eth1 netif.eth2" format) is required; MTU is optional and will be used if provided.

bridge -- this is a standard bridge interface, where you want the bridge to be configured with an IP address. Required variables are IP and NM. SLAVES (in SLAVES="netif.eth0 netif.eth1" format,) GW, MTU, DOM, NS1 and NS2 are optional and will be used appropriately if supplied.

bridge-noip -- this is a standard bridge interface, for when you don't want to assign an IP to the bridge. The sole supported variable is SLAVES, which is optional.

Template Dependencies

By default, the Funtoo core-netif scripts will auto-create need dependencies for any interfaces listed in any specified SLAVES variables. So a netif.bond0 script with a SLAVES="netif.eth1 netif.eth2" setting will automatically need netif.eth1 and netif.eth2. This will ensure that the slave interfaces are properly configured before they are enslaved into a bond device or added to a bridge.

Completed Template

A completed /etc/conf.d/netif.eth0 template file might look like this:

template="interface"
description="my public interface"

IP=172.16.1.1
NET=172.16.0.0
NM=255.255.0.0
GW=172.16.0.1
DOM=funtoo.org
NS1=129.1.2.1
NS2=129.1.2.2

DHCP-based IP Auto-Configuration

Funtoo's core-netif system offers a lot of flexibility for configuring network interfaces, essentially acting as a "network interface construction kit."

However, many systems now configure their interfaces dynamically. For these systems, Funtoo's core-netif system can be completely bypassed and dhcpcd can be used. dhcpcd 5.x, available by default in Funtoo Linux, is capable of managing all interfaces by default.

Network configuration via DHCP is exetremely simple. There is no need to create perform any steps other than enabling dhcpcd 5.x as follows:

# rc-update add dhcpcd default
# rc

dhcpcd 5.x has been designed to manage all available network interfaces, automatically bringing them up and attempting to acquire DHCP lease information for them. Once a DHCP lease has been acquired, the network interface will be auto-configured using this information. dhcpcd will take care of all configuration for you, including dynamic management of name server information using the openresolv framework.

Wireless Configuration

For wireless networks, you will first want to enable wireless extensions in your kernel, the appropriate wireless modules, and emerge wireless-tools:

# emerge wireless-tools

I also recommend you emerge wpa_supplicant 0.6.9 or later, which includes an OpenRC-compatible initscript that is compatible with Funtoo as well. wpa_supplicant implements modern WPA/WPA2 wireless link-layer encryption, which is necessary for connecting to most modern password-protected wireless networks. After emerging, add to your default runlevel as follows:

# rc-update add wpa_supplicant default

If you have an Intel wireless adapter, then you will likely need to install the latest microcode for your device in addition to ensuring that the proper Intel Wireless kernel drivers are available. For my Intel Corporation PRO/Wireless AGN [Shiloh] Network Connection, I need to do the following:

# emerge net-wireless/iwl5000-ucode

udev (running by default) and the Linux kernel firmware loader support (CONFIG_FW_LOADER) will automatically load the microcode when needed.

Note that Gentoo and Funtoo provide different versions of the Intel microcode because the version you need will depend on the kernel you are using. For my RHEL5-based kernel, I had emerge an older version of the microcode to match what my kernel wireless driver was expecting by typing:

# emerge =net-wireless/iwl5000-ucode-5.4.0.11

This installed this file iwlwifi-5000-1.ucode which was required by my RHEL5-based kernel. Just typing emerge net-wireless-iwl5000-ucode installed iwlwifi-500-2.ucode, which my kernel could not use. Before I had the right version of the microcode, I saw an error like this when I viewed the kernel messages by typing dmesg:

iwl5000: iwlwifi-5000-1.ucode firmware file req failed: Reason -2

This error message generally means "I can't find this file ``iwlwifi-5000-1.ucode`` that I'm looking for in ``/lib/firmware``." With the proper firmware in place, then the wireless driver will be happy and wpa-supplicant can then bring the wireless interface up.

The only remaining step is to use the wpa_passphrase utility to store hashed keys (passwords) that wpa_supplicant can use to connect to your favorite wireless networks. This is done as follows:

# wpa_passphrase jims-netgear >> /etc/wpa_supplicant/wpa_supplicant.conf
<enter your passphrase>

Now, when wpa_supplicant encounters an SSID of jims-netgear, it will use the password you entered to authenticate with this access point.

At this point, ensure that dhcpcd has been enabled in your current runlevel and type rc to start everything up. wpa_supplicant should be able to automatically associate with SSIDs in its config file, at which point dhcpcd will take over and acquire an IP address from a DHCP server. This should all happen seamlessly. Use the iwconfig command to see if you have successfully associated with an access point.

The OpenResolv Framework

openresolv is a framework used by dhcpcd and the Funtoo Linux core-netif templates to manage nameserver settings. openresolv allows you to dynamically add per-interface name server information. When the interface is brought up, this name server information is added using the resolvconf command, and resolvconf takes care of adding it to /etc/resolv.conf. When the interface is eventually brought down, these entries are removed from /etc/resolv.conf by openresolv. This is a much better way to manage name server information than the usual method of manually modifying /etc/resolv.conf, since it handles changes to the name server configuration in a much more dynamic and elegant way. Funtoo's core-netif templates as well as dhcpcd automatically take advantage of openresolv.

Other Network Configurations

If you have a network configuration template that might be useful to others, please post it to the funtoo-dev mailing list so we can review it and possibly incorporate it into Funtoo.

About the Author

This is not really me

Daniel Robbins is the founder of the Gentoo community and creator of the Gentoo Linux operating system. Daniel resides in New Mexico with his wife Mary and two energetic daughters, and is founder and lead of Funtoo. Daniel has also written many technical articles for IBM developerWorks, Intel Developer Services and C/C++ Users Journal.