Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary heading Template:Article summary link Template:Article summary end
From the netcfg man page:
- 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.
- 1 Preparation
- 2 Installation
- 3 Configuration
- 4 Usage
- 5 Connecting automatically
- 6 Tips and tricks
- 7 Troubleshooting
- 7.1 Debugging
- 7.2 Network unavailable
- 7.3 Wireless association failed
- 7.4 Unable to get IP address with DHCP
- 7.5 Not a valid connection, check spelling or look at examples
- 7.6 Driver quirks
- 7.7 Ralink legacy drivers rt2500, rt2400 that use iwpriv
- 7.8 find: "/var/run/network//suspend/": No such file or directory
- 7.9 It still doesn't work, what do I do?
- 8 FAQ
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, gateway and name server addresses 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 (SSID), and any password or encryption keys. Additionally, ensure the proper drivers and firmware are installed for the wireless device, as described in Wireless Setup.
Ensure you have the latest version of netcfg installed. Older versions have more bugs and may not work well with the latest drivers. The Template:Package Official package is available in core:
# pacman -S netcfg
As of version 2.5.x, optional dependencies include Template:Package Official – required for automatic/roaming wireless connection – and Template:Package Official – required for automatic ethernet configuration. (More information.)
# pacman -S wpa_actiond ifplugd
Network profiles are stored in the Template:Filename directory. To minimize the potential for errors, copy an example configuration from Template:Filename to Template:Filename. 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 Template:Filename as a base. Be wary of examples found on the Internet as they often contain deprecated options that may cause problems.
|Connection type/security||Example profile|
|Wireless; WEP hex key||Template:Filename|
|Wireless; WEP string key||Template:Filename|
|Wireless; WPA personal (passphrase)||Template:Filename|
|Wireless; WPA enterprise|| Template:Filename (wpa_supplicant configuration is external) |
Template:Filename (wpa_supplicant configuration stored as string)
|Wired; static IP||Template:Filename|
|Wired; iproute configuration||Template:Filename|
Next, modify the new configuration file, Template:Filename:
- Set Template:Codeline to the correct wireless or ethernet interface. This can be checked with Template:Codeline and Template:Codeline.
- Ensure the Template:Codeline and Template:Codeline (passphrase) are set correctly for wireless connections. Typos in these fields are common errors.
To connect a profile:
# netcfg mynetwork
To disconnect a profile:
# netcfg down <profile-name>
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
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 Template:Filename directory first (see #Configuration).
Template:Codeline allows users to connect profiles during boot.
Additionally, the Template:Package Official package is required.
Template:Codeline allows users to automatically connect to wireless networks with proper roaming support.
Additionally, the Template:Package Official package is required. Note that wpa-config profiles does not work with net-auto-wireless. Convert them to wpa-configsection instead.
Template:Codeline allows users to automatically connect to wired networks.
To enable this feature, users must install ifplugd
# pacman -S ifplugd
The daemon starts an ifplugd process which runs Template:Filename 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.
Note2: The net-auto-wired daemon cannot start multiple ifplugd processes for multiple interfaces (unlike ifplugd's own /etc/rc.d/ifplugd which can).
Tips and tricks
Passing arguments to iwconfig before connecting
Simply add the following to a profile:
For example, force the card to register to a specific access point given by MAC address:
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 (Template:Filename; see #Per-interface configuration).
RFKILL=soft # can be either 'hard' or 'soft'
For example, on an Eee PC:
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 Template:Codeline, Template:Codeline, Template:Codeline, and Template:Codeline 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="ifconfig 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"
Configuration options that apply to all profiles using an interface can be set using Template:Filename. For example:
This is useful for Template:Codeline options, rfkill switch support, pre/post up/down scripts and Template:Codeline. These options are loaded before profiles so that any profile-based options will take priority.
Template:Filename may contain any valid profile option, though you are likely to use Template:Codeline/Template:Codeline and Template:Codeline/Template:Codeline (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
netcfg has limited support to load hooks that handle output. By default it loads the Template:Filename hook which provides the familiar output that you see. A syslog logging hook is also included. These can be found at Template:Filename.
A Qt-based netcfg front-end called ArchAssistant exists. It proposes to manage and connect/disconnect profiles from a systray icon. Automatic wireless detection is also available. This tool is particularly useful for laptop users.
- archassistant in the AUR
- archassistant on kde-apps.org
- archassistant package on archlinux.fr: i686 and x86_64
There is also a relatively new GUI for netcfg2 on qt-apps.org that does only network configuration. You can find it here.
There is a console tool for selecting wireless networks in "real-time" (in NetworkManager manner) 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 type Template:Codeline and choose the network you need.
The tool is currently packaged and available in [community] repository. To install:
# pacman -S wifi-select
wifi-select does the following:
- parses iwlist scan results and presents list of networks along with its 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, WiFi hotspot), wifi-select automatically generates new profile with corresponding $SECURITY and asks for the key (if needed). It uses DHCP as $IP by default
- then, if connection succeeds, profile is saved for later usage
- if connection fails, user is asked if he/she wants to keep generated profile for further usage (for example to change $IP to static or adjust some additional options)
- Forum thread related to development of wifi-select
- wifi-select in the AUR
- wifi-select Mercurial repository
# NETCFG_DEBUG="yes" netcfg <arguments>
Debugging information for wpa_supplicant can be logged using Template:Codeline within a profile, for example:
Whatever is entered here will be added to the command when wpa_supplicant is called.
This error is typically due to:
- Out of range; or
- Driver issue.
Wireless association failed
This error is typically due to:
- Out of range/reception;
- Incorrect configuration;
- Invalid key;
- Driver problem; or
- Trying to connect to a hidden network.
If an AP with a hidden SSID is used, try:
PRE_UP='iwconfig $INTERFACE essid $ESSID'
Unable to get IP address with DHCP
This error is typically due to:
- Out of range/reception
Not a valid connection, check spelling or look at examples
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.
- Run Template:Codeline before attempting to connect (broadcom)
- Run Template:Codeline before attempting to connect (ipw3945, broadcom and Intel PRO/Wireless 4965AGN)
- Same as previous, run before starting Template:Codeline. Not supported anymore - use
IWCONFIG="essid $ESSID"instead. (ath9k)
- Take interface down before association and then restore it after (madwifi)
- Sleep one second before checking if the association was successful
- Run Template:Codeline after associating
Add the required quirks to the netcfg configuration file Template:Filename, for example:
If you receive "Wireless network not found", "Association failed" errors and have tried the above, or if an AP with a hidden SSID is used, see the above section #Wireless association failed.
There is no plans to add WPA support to these drivers. rt2x00 is supported, however, and will replace these.
find: "/var/run/network//suspend/": No such file or directory
If you get this error message then don't bother because it is a known bug. Create the directory by hand.
It still doesn't work, what do I do?
If this article did not help solve your problem, the next best place to ask for help is the forums or the mailing list.
To be able to determine the problem, we need information. When you ask, provide the following output:
- ALL OUTPUT FROM netcfg
- ALL OUTPUT FROM netcfg
- ALL OUTPUT FROM netcfg
- This is absolutely crucial to be able determine what went wrong. The message might be short or non-existent, but it can mean a great deal.
- Template:Filename network profiles
- This is also crucial as many problems are simple configuration issues. Feel free to censor your wireless key.
- netcfg version