Difference between revisions of "Netcfg"

From ArchWiki
Jump to: navigation, search
(Remove example, as they are included with netcfg)
(Proxy settings removed, as this would not even work. Bash exports are only seen by child processes, netcfg spawns none that need proxy info.)
Line 21: Line 21:
{{Box Note | Example profiles are located in /etc/network.d/examples/. Modifying an example from here is the best way to ensure that you have a configuration suitable for your version of netcfg. }}
{{Box Note | Example profiles are located in /etc/network.d/examples/. Modifying an example from here is the best way to ensure that you have a configuration suitable for your version of netcfg. }}
===Proxy settings===
Just use the PRE_UP value to set environment variables as described in [[Proxy settings]]. Here is an example:
PRE_UP="http_proxy=; export http_proxy;"
{{Note|using POST_DOWN to unset the ''protocol''_proxy variable(s) might not be a good idea because, given two profiles "a" and "b" which both set and "clean" the http_proxy variable:
*you up a then b
*you down a
the result is that the http_proxy variable is empty even if b is still up and need its proxy.}}
==Step 3: Connect==
==Step 3: Connect==

Revision as of 04:54, 12 May 2009

Template:I18n links start Template:I18n entry Template:I18n entry Template:I18n entry Template:I18n links end

Step 1: Install

Network profiles are handled by the bash scripts available in the netcfg package.

# pacman -Sy core/netcfg

For information relating to the latest development version of netcfg, see Network Profiles development

Step 2: Create the profile(s)


A profile is a single text file in /etc/network.d which defines variables used by netcfg. The file name will become the name of the profile, and can be anything you wish, it is not a setting involved in the connection.

The easiest way to create a new profile is to copy one of the example profiles from /etc/network.d/examples and edit it to fit with your network.

Template:Box Note

Template:Box Note

Step 3: Connect

To connect a profile just execute the following command as root:

# netcfg <profile-name>


Wireless connections

For wireless connections, make sure the required drivers and firmwares are installed as explained in Wireless Setup.

Network unavailable

This is typically one of:

  • Out of range
  • Driver issue (See Driver Quirks above)
  • Trying to connect to a hidden network

If you know your network is hidden, set


Wireless Association failed

This is typically one of:

  • Out of range/reception
  • Incorrect configuration
  • Invalid key
  • Driver problem (See Driver Quirks above)

If it is a range problem, increasing TIMEOUT= can help.

Unable to get IP address with DHCP

This is typically one of:

  • Out of range/reception

Try increasing DHCP_TIMEOUT

Not a valid connection, check spelling or look at examples

You must set CONNECTION= to "ethernet", "ppp", or "wireless".

Using a string WEP key

This is for a STRING WEP key, not a HEX WEP key, not a WPA key.


Ralink legacy drivers rt2500, rt2400 that use iwpriv

I have no intention of supporting these. rt2x00 is supported, however, and will replace these.

If you must use them, create a shell script that runs the needed iwpriv commands and put its path in PRE_UP=""

Passing arguments to iwconfig before connecting



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

For example, setting bssid/ap mac:

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

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

Driver Quirks (netcfg 2.1 and later)

You probably do not need these, ensure your configuration is correct and sane before you attempt to use any quirks

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

  • prescan - Run "iwlist $INTERFACE scan" before attempting to connect (Some broadcom)
  • preessid - Run "iwconfig $INTERFACE essid $ESSID" before attempting to connect. (Some ipw3945 and Intel PRO/Wireless 4965AGN)
  • wpaessid - Same as previous, run before starting wpa_supplicant
  • predown - Take interface down before association and then restore it after. (madwifi)
  • postsleep - Sleep 1 second before checking if the association was successful
  • postscan - Run "iwlist scan" after associating

For example

QUIRKS=(prescan preessid)

If you are having problems with DNS and DHCP, try adding to your profile:


This will tell netcfg to use dhcpcd instead of dhclient

If you get "Wireless Network Not Found" or "Association Failed" and have tried the above, try:


It still doesn't work, what do I do ?

If the FAQs below didn't solve your problem the next best place to go is the forums, or the mailing list.

To be able to determine what's wrong, we need information so when you post, make sure that you provide the following output:

  • ALL OUTPUT FROM netcfg
  • ALL OUTPUT FROM netcfg
  • ALL OUTPUT FROM netcfg - this is absolutely cruicial to be able determine what went wrong. The message might be short or nonexistant, but it can mean a great deal.
  • Your /etc/network.d network profiles - Also cruicial as many problems are simple config issues. Feel free to censor your wireless key.
  • netcfg version
  • lsmod
  • iwconfig

Step 4: Connecting on boot


net-profiles allows you to start some profiles on boot.

In order to do that you need to list the /etc/network.d/ profiles you want netcfg to try at boot in the NETWORKS=() line in /etc/rc.conf.

NETWORKS=(home mywireless)

You also need to add net-profiles to the DAEMONS array, eg: DAEMONS=(... net-profiles ...).

Display a menu at boot

net-profiles can also display a menu so you can pick which profile you want to set up. For that you just need to set NETWORKS= to menu (ie NETWORKS=menu).

You can also access that menu at any time by running netcfg-menu in a terminal.

The dialog package is needed.

Automatic detection


net-auto is the second boot-time script of the netcfg package. Its function is to determine automatically which profile should be started.

net-auto reads the AUTO_NETWORKS=() line in /etc/rc.conf. For example:

AUTO_NETWORKS=(auto-wireless wlan0)

Like net-profiles it needs to be added to the DAEMONS=() line.

To run after boot:

# /usr/bin/netcfg-auto-wireless $interface


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

Links: archassistant on AUR | archassistant on kde-apps.org | archassistant package on archlinux.fr i686 and x86_64

Supplementary tools

There is a console tool for selecting wireless networks "in real-time" (in NetworkManager manner) called wifi-select. The tool is convinient for use in wifi-cafe or another places you are visiting for the first (and maybe the last) time. Then you don't need to create the file-profile for a new network, just type sudo wifi-select wlan0 and choose the network you need.

The tool is currently packaged and available in AUR (yaourt -S wifi-select).

It works as follows:

  • 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 network from wifi-cafe he currently visited), 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)

Links: Forum thread related to development of wifi-select | wifi-select on AUR | wifi-select mercurial repository


Why doesnt netcfg do x?

netcfg doesn't need to. It connects to networks.

But netcfg is super modular and re-usable. Have a look at /usr/lib/networks/ -- heaps of reusable functions for your own scripts.

Why doesn't netcfg behave in this way? It makes more sense

netcfg doesn't enforce any rules. It's task is to connect to networks. It doesn't impose any heuristics, like 'disconnect from wireless if ethernet is connected'.

If you want behaviour like that, it'd be really easy to write a separate tool over netcfg. See the question above.

Do I still need x when I'm using netcfg?

  • /etc/hosts: Yes, you still need this, this is important. Don't remove your hostname from this otherwise you'll have some odd problems.
  • HOSTNAME= in /etc/rc.conf: It's strongly recommended you keep this, otherwise no hostname will be set if a profile fails
  • DAEMONS=(network) and INTERFACES=() in /etc/rc.conf: If you've setup all your networks with netcfg instead, yes, you can remove this. You can also safely remove lo, it's been moved into rc.sysinit.
  • lo: This is now in rc.sysinit, you don't need to configure it anywhere.