netcfg is used to configure and manage network connections via profiles. It has pluggable support for a range of connection types, such as wireless, ethernet, ppp. It is also capable of starting/stopping many to one connections, that is, multiple connections within the same profile, optionally with bonding.

netcfg is useful for users seeking a simple and robust means of managing multiple network configurations (e.g. laptop users). For systems connecting to a single network, the network daemon may be more appropriate.

Preparation

In the simplest cases, users must at least know the name of their network interface(s) (e.g. eth0, wlan0). If configuring a static IP address, the IP addresses of the default gateway and name server(s) must also be known.

If connecting to a wireless network, have some basic information ready. For a wireless network this includes what type of security is used, the network name (ESSID), and any password or encryption keys. Additionally, ensure the proper drivers and firmware are installed for the wireless device, as described in Wireless Setup.

Installation

Ensure you have the latest version of netcfg installed. Older versions have more bugs and may not work well with the latest drivers. The netcfg package is available in the official repositories.

If you want to have Bash completion support for netcfg, install the bash-completion package from the official repositories.

Configuration

Network profiles are stored in the /etc/network.d directory. To minimize the potential for errors, copy an example configuration from /etc/network.d/examples/ to /etc/network.d/mynetwork. The file name is the name of the network profile ("mynetwork" is used as an example throughout this article). The name is not a network setting and does not need to match the wireless network name (SSID).

Depending on the connection type and security, use one of the following examples from /etc/network.d/examples as a base. Be wary of examples found on the Internet as they often contain deprecated options that may cause problems.

Set INTERFACE to the correct wireless or Ethernet interface. This can be checked with ip link and iwconfig.

Ensure the ESSID and KEY (passphrase) are set correctly for wireless connections. Typos in these fields are common errors.

Note that WEP string keys (not hex keys) must be specified with a leading s: (e.g. KEY="s:somepasskey").

Note: netcfg configurations are valid Bash scripts. Any configuration involving special characters such as $ or \ needs to be quoted correctly otherwise it will be interpreted by Bash. To avoid interpretation, use single quotes or backslash escape characters where appropriate.

Note: Network information (e.g. wireless passkey) will be stored in plain text format, so users may want to change the permissions on the newly created profile (e.g. chmod 0600 /etc/network.d/mynetwork to make it readable by root only).

Note: For WPA-Personal, it is also possible to use WPA passkey encoded into a hexadecimal string, instead of as a plain text passkey.

Follow the procedure on the WPA supplicant page's first example exercise to generate a hexadecimal string from you WPA passkey.
Save the new hexadecimal string into your wireless WPA profile in /etc/network.d/mynetwork as the value of the KEY variable (make sure this will be the only KEY variable enabled), to look similar to this (replace the string with your one):

Usage

If successful, users can configure netcfg to connect automatically or during boot. If the connection fails, see #Troubleshooting for solutions and how to get help.

For other functions, see:

$ netcfg help

Connecting automatically

Several methods are available to users wanting to automatically connect network profiles (e.g. during boot or whilst roaming). Note that a network profile must be properly configured within the /etc/network.d directory first (see #Configuration).

Tip: If enabling one of the following daemons and nothing is configured within the INTERFACES array in /etc/rc.conf, you may remove the network daemon from the DAEMONS array. If you mount NFS shares during boot, ensure the netfs daemon remains listed, though (otherwise the network will be dropped before unmounting shares during shutdown).

net-profiles

net-profiles allows users to connect profiles during boot.

To enable this feature, users must add net-profiles to the DAEMONS array in /etc/rc.conf and specify profiles to try in the NETWORKS array:

/etc/rc.conf

NETWORKS=(mynetwork yournetwork)
...
DAEMONS=(... net-profiles ...)

Alternatively, net-profiles can be configured to display a menu – allowing users to choose a desired profile – by setting the contents of the NETWORKS array to menu:

net-auto-wired

To enable this feature, users must installifplugd, then add net-auto-wired to the DAEMONS array in /etc/rc.conf and specify the desired wired interface with the WIRED_INTERFACE variable:

/etc/rc.conf

WIRED_INTERFACE="eth0"
...
DAEMONS=(... net-auto-wired ...)

The daemon starts an ifplugd process which runs /etc/ifplugd/netcfg.action when the status of the wired interface changes (e.g. a cable is plugged in or unplugged). On plugging in a cable, attempts are made to start any profiles with CONNECTION = "ethernet" or "ethernet-iproute" and INTERFACE = WIRED_INTERFACE until one of them succeeds.

Note: DHCP profiles are tried before static ones, which could lead to undesired results in some cases. However, one can tell netcfg to prefer a particular interface by adding AUTO_WIRED=1 to the desired profile.

Tips and tricks

Passing arguments to iwconfig before connecting

Where <arguments> can be any valid iwconfig argument. The script then runs iwconfig $INTERFACE $IWCONFIG.

For example, force the card to register to a specific access point given by MAC address:

IWCONFIG="ap 12:34:56:78:90:12"

This supersedes the IWOPTS and WEP_OPTS options which were incompletely implemented.

rfkill (enable/disable radio power)

netcfg can enable/disable radio for wireless cards equipped with software control of radio. For wireless cards with hardware switches, netcfg can detect disabled hardware switches and fail accordingly.

To enable rfkill support, you need to specify what sort of switch the wireless interface has; hardware or software. This can be set within a profile or at the interface level (/etc/network.d/interfaces/$INTERFACE; see #Per-interface configuration).

RFKILL=soft # can be either 'hard' or 'soft'

For some kill switches the rfkill entry in /sys is not linked to the interface and the RFKILL_NAME variable needs to be set to the contents of the matching /sys/class/rfkill/rfkill#/name.

For example, on an Eee PC:

RFKILL=soft
RFKILL_NAME='eeepc-wlan'

On a mid-2011 Thinkpad:

RFKILL=hard
RFKILL_NAME='phy0'

Note: The net-auto-wireless daemon requires an interface level configuration of rfkill or it will not start.

Warning: Some devices (at least few SiS cards) can create /sys/class/rfkill/rfkill# entries with different names on every switch. Something like this will work in such cases (wifi-only solution!):

Execute commands before/after interface up/down

If your interface requires special actions prior/after the establishment/closure of a connection, you may use the PRE_UP, POST_UP, PRE_DOWN, and POST_DOWN variables.

For example, if you want to configure your wireless card to operate in ad-hoc mode but you can only change modes when the interface is down, you could use something like this:

PRE_UP="ip link set wlan0 down; iwconfig wlan0 mode ad-hoc"

Or if you want to mount your network shares after a successful connection, you could use:

POST_UP="sleep 5; mount /mnt/shares/nexus/utorrent 2>/dev/null"

Sometimes you may want to run something from netcfg with another user:

POST_UP="su -c '/you/own/command' username"

Note: If the commands specified in these properties return anything other than 0 (success), netcfg aborts the current operation. So if you want to mount a certain network share that might not be available at the time of connection (thus returning an error), you could create a separate Bash script with the mount commands and a exit 0 at the end. Alternatively you can add || true to the end of the command that may fail.

Intermittent Connection Failure

Some driver+hardware combinations drop associations sometimes. Use the pre and post commands to add/remove the driver and use a script like the following to fix the current connection:

Per-interface configuration

Configuration options that apply to all profiles using an interface can be set using /etc/network.d/interfaces/$INTERFACE. For example:

/etc/network.d/interfaces/wlan0

This is useful for wpa_supplicant options, rfkill switch support, pre/post up/down scripts and net-auto-wireless. These options are loaded before profiles so that any profile-based options will take priority.

/etc/network.d/interfaces/$INTERFACE may contain any valid profile option, though you are likely to use PRE_UP/DOWN and POST_UP/DOWN (described in the previous section) or one of the options listed below. Remember that these options are set for all profiles using the interface; you probably do not want to connect to your work VPN here, for instance, as it will try to connect on every wireless network!

WPA_GROUP - Setting the group of the wpa_ctrl interface
WPA_COUNTRY - Enforces local regulatory limitations and allows use of more channels
WPA_DRIVER - Defaults to wext, may want nl80211 for mac80211 devices

Output hooks

netcfg has limited support to load hooks that handle output. By default it loads the arch hook which provides the familiar output that you see. A syslog logging hook is also included. These can be found at /usr/lib/network/hooks.

ArchAssistant (GUI)

A Qt-based netcfg front-end called ArchAssistant exists. It proposes to manage and connect/disconnect profiles from a system tray icon. Automatic wireless detection is also available. This tool is particularly useful for laptop users.

There is also a relatively new GUI for netcfg on qt-apps.org that does only network configuration. You can find it here.

wifi-select

There is a console tool for selecting wireless networks in "real-time" (in NetworkManager fashion) called wifi-select. The tool is convenient for use in Internet cafés or other places you are visiting for the first (and maybe the last) time. With this tool, you do not need to create a profile for a new network, just run wifi-select wlan0 as root and choose the desired network.

parses iwlist scan results and presents a list of networks along with their security settings (WPA/WEP/none) using dialog

if user selects network with existing profile -- just use this profile to connect with netcfg

if user selects a new network (for example, a Wi-Fi hotspot), wifi-select automatically generates a new profile with corresponding $SECURITY and asks for the key (if needed). It uses DHCP as $IP by default

then, if the connection succeeds, the profile is saved for later usage

if the connection fails, the user is asked if he or she wants to keep generated profile for further usage (for example to change $IP to static or adjust some additional options)

Then add the corresponding bridge name to your NETWORKS=(...) in /etc/rc.conf.

It can be brought up by calling it directly, or by restarting net-profiles.

netcfg br0

rc.d restart net-profiles

Adding multiple IP addresses to one interface

If you want to assign multiple IP addresses to 1 specific interface, this can be done by issuing the relevant ip command in a POST_UP statement (which as the name suggests will be executed after the interface has been brought up). Multiple statements can be separated with a ;. So if you for example would want to assign both 10.0.0.1 and 10.0.0.2 to interface eth0; the config would look something among the lines of:

Adding static routes

When wanting to configure static routes, this can be done by issuing the relevant ip command in a POSTUP statement (which as the name suggests will be executed after the interface has been brought up). Optionally, a PRE_DOWN statement can be added to remove said routes when the interface is brought down. Multiple statements can be separated with a ;. In the below example we'll route 10.0.1.0/24 over interface eth1 and then remove the route when the interface is brought down.

Unable to get IP address with DHCP

Not a valid connection, check spelling or look at examples

You must set CONNECTION to one of the connection types listed in the /usr/lib/network/connections directory. Alternatively, use one of the provided configuration examples in /etc/network.d/examples.

No Connection

If you get a set of debug messages similar to the following (remembering that profile names and interface names may be different), it could be that the process of bringing up the interface is taking too long.

Driver quirks

Note: You most likely do not need quirks; ensure your configuration is correct before considering them. Quirks are intended for a small range of drivers with unusual issues, many of them older versions. These are workarounds, not solutions.

Some drivers behave oddly and need workarounds to connect. Quirks must be enabled manually. They are best determined by reading the forums, seeing what others have used, and, if that fails, trial and error. Quirks can be combined.