Difference between revisions of "Netcfg"

From ArchWiki
Jump to: navigation, search
m (Do not use -Sy when installing packages)
(New version, docs needed overhauling to reduce duplication.)
Line 6: Line 6:
 
{{i18n_links_end}}
 
{{i18n_links_end}}
  
==Quickstart==
+
=Quick Start - netcfg in 4 easy steps=
===Step 1===
+
 
 +
Have some basic information about your wireless network ready. For a wireless network this includes what type of security is used, network name and any password or encryption keys.
 +
 
 +
netcfg is profile based. Each network has an individual profile. These profiles can be individually connected/disconnected at any time. The profile configuration varies depending on whether it's a wireless, ethernet or other type of connection. The available options are documented on the netcfg website and in the included examples.
 +
 
 +
==Step 1==
 +
Ensure you have the latest version of netcfg installed. Older versions have more bugs and may not work well with the latest drivers.
 +
 
 
  # pacman -S netcfg
 
  # pacman -S netcfg
  
===Step 2===
+
==Step 2==
Copy an example configuration from /etc/network.d/examples/  to /etc/network.d/mynetwork. You may use another name instead of "mynetwork".
+
Copy an example configuration from /etc/network.d/examples/  to /etc/network.d/mynetwork. The filename is the name of the network profile, "mynetwork" is used as an example throughout this quickstart. The name is not a network setting and does not need to match your wireless network name (SSID).
 +
 
 +
Depending on your security and connection, 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.
  
Depending on your security and connection, use the following examples from /etc/network.d/examples/
 
 
* '''WEP hex key'''  wireless-wep
 
* '''WEP hex key'''  wireless-wep
 
* '''WEP string key''' wireless-wep-string-key
 
* '''WEP string key''' wireless-wep-string-key
* '''WPA passphrase''' wireless-wpa
+
* '''WPA personal (passphrase)''' wireless-wpa
* '''WPA enterprise''' wireless-wpa-config
+
* '''WPA enterprise''' wireless-wpa-config (wpa_supplicant configuration is external) or wireless-wpa-configsection (wpa_supplicant configuration stored as string)
* '''WPA enterprise/passphrase''' wireless-wpa-configsection (new in netcfg 2.5)
+
 
* '''Wired connection - dhcp''' ethernet-dhcp
 
* '''Wired connection - dhcp''' ethernet-dhcp
 
* '''Wired connection - static IP''' ethernet-static
 
* '''Wired connection - static IP''' ethernet-static
 
* '''Wired connection - iproute configuration''' ethernet-iproute
 
* '''Wired connection - iproute configuration''' ethernet-iproute
  
===Step 3===
+
{{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 | Your network information (e.g. wireless passkey) will be stored in plain text format, so you may want to change the permissions on the newly created /etc/network.d/*.conf file (e.g. <tt>chmod 0600 /etc/network.d/*.conf</tt> to make it readable by root only), depending upon how security conscious you are. }}
 +
 
 +
==Step 3==
 
Modify your configuration file new configuration file, /etc/network.d/mynetwork
 
Modify your configuration file new configuration file, /etc/network.d/mynetwork
  
 
* Set INTERFACE= to your wireless or ethernet interface. This can be checked with ifconfig and iwconfig.
 
* Set INTERFACE= to your wireless or ethernet interface. This can be checked with ifconfig and iwconfig.
* '''Wireless''' - Make sure you set your ESSID and KEY correctly. Typos in these are common errors.
+
* Make sure you set your ESSID and KEY/passphrase correctly. Typos in these are common errors.
* '''Wireless - WPA Enterprise''' - You'll need to use an external wpa_supplicant configuration.
+
  
===Step 4===
+
==Step 4==
 
To connect, simply execute:
 
To connect, simply execute:
 
  # netcfg mynetwork
 
  # netcfg mynetwork
 +
 +
To disconnect from a profile:
 +
# netcfg down <profile-name>
  
 
If it does not work, have a look at the [[Network Profiles#Troubleshooting|troubleshooting section]] for solutions and how to get help.
 
If it does not work, have a look at the [[Network Profiles#Troubleshooting|troubleshooting section]] for solutions and how to get help.
Line 38: Line 51:
 
If all goes to plan, you can configure it to  [[Network Profiles#Step 4: Connecting on boot|connect automatically or on boot]].
 
If all goes to plan, you can configure it to  [[Network Profiles#Step 4: Connecting on boot|connect automatically or on boot]].
  
==Step 1: Install==
+
For more command line arguments, see
Network profiles are handled by the bash scripts available in the netcfg package.
+
  # netcfg help
 
+
  # pacman -S netcfg
+
  
For information relating to the latest development version of netcfg, see [[Network Profiles development]]
+
=Configuration Notes=
 
+
==Using a string WEP key==
==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 use one of the example profiles and edit it to fit with your network.
+
 
+
cp /etc/network.d/example/<profile> /etc/network.d/
+
 
+
The files are allowed to be read as a regular user.  If you plan on storing a wireless passkey in this file (stored as regular text) or want to keep regular user from being able to read this file, you should change it's permissions:
+
 
+
chmod 600 /etc/network.d/<profile>
+
 
+
===Configuration Notes===
+
 
+
Details on some configuration options you may need to know.
+
 
+
====Using a string WEP key====
+
 
This is for a STRING WEP key, not a HEX WEP key, not a WPA key.
 
This is for a STRING WEP key, not a HEX WEP key, not a WPA key.
 
  KEY="s:Somepasskey"
 
  KEY="s:Somepasskey"
  
====Ralink legacy drivers rt2500, rt2400 that use iwpriv====
+
==Ralink legacy drivers rt2500, rt2400 that use iwpriv==
 
There is no plans to add WPA support to these drivers. rt2x00 is supported, however, and will replace these.
 
There is no plans to add WPA support to these drivers. 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=""
 
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====
+
==Passing arguments to iwconfig before connecting==
 
Simply:
 
Simply:
  
Line 81: Line 76:
 
This supercedes the IWOPTS and WEP_OPTS options which were incompletely implemented.
 
This supercedes the IWOPTS and WEP_OPTS options which were incompletely implemented.
  
====Execute commands before/after interface up/down====
+
=Connecting automatically and/or on boot=
If your interface requires special actions prior/after the establishment/closure of a connection, you may use the '''PRE_UP''', '''POST_UP''', '''PRE_DOWN''', '''POST_DOWN''' properties.
+
==net-profiles - Connect a specific list of profiles==
 +
<code>net-profiles</code> allows you to start some profiles on boot.
  
For example, if you want to set your wlan card to operate in ad-hoc mode but you can only change it when the interface is down, you could use something like this:
+
In order to do that you need to list the /etc/network.d/ profiles you want netcfg to try at boot in the <code>NETWORKS=()</code> line in /etc/rc.conf.
  
  PRE_UP="ifconfig wlan0 down; iwconfig wlan0 mode ad-hoc"
+
  NETWORKS=(home mywireless)
  
Or if you want to mount your network shares after a successful connection, you could use:
+
You also need to add <code>net-profiles</code> to the DAEMONS array
  
POST_UP="sleep 5; mount /mnt/shares/nexus/utorrent 2>/dev/null;"
+
If you have nothing configured within the INTERFACES array, you may remove the "network" daemon from the daemons line.
  
{{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 <nowiki>"|| true"</nowiki> to the end of the command that may fail.}}
+
==net-auto-wireless - Automatically connect to, and roam between wireless networks==
  
==Step 3: Connect==
+
In your /etc/rc.conf, add a line setting WIRELESS_INTERFACE to your wireless device. For example:
To connect to a profile just execute the following command ''as root'':
+
  WIRELESS_INTERFACE="wlan0"
  # netcfg <profile-name>
+
To disconnect from a profile:
+
# netcfg down <profile-name>
+
  
Where <profile-name> is the name of the file created in /etc/network.d. For example /etc/network.d/homewireless would simply have a profile name of homewireless
+
Then add <code>net-auto-wireless</code> to the DAEMONS array.
  
==Step 4: Connecting on boot==
+
This requires appropriate profiles to be made for the networks in /etc/network.d/
===net-profiles===
+
<code>net-profiles</code> 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 <code>NETWORKS=()</code> line in /etc/rc.conf.
+
==net-auto-wired==
  
  NETWORKS=(home mywireless)
+
In your /etc/rc.conf, add a line setting WIRED_INTERFACE to your wired device. For example:
 +
  WIRED_INTERFACE="eth0"
  
You also need to add <code>net-profiles</code> to the DAEMONS array, eg: DAEMONS=(... '''net-profiles''' ...).
+
Then add <code>net-auto-wired</code> to the DAEMONS array.
  
If you are only using a laptop, with little-to-no use of ethernet, you may want to delete the Network Daemon to resolve boot issues.  
+
This requires appropriate profiles to be made for the networks in /etc/network.d/
  
====Display a menu at boot====
+
==netcfg-menu - Display a menu at boot where a profile may be selected==
 
<code>net-profiles</code> 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:
 
<code>net-profiles</code> 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:
  
Line 123: Line 115:
 
  NETWORKS=(menu)
 
  NETWORKS=(menu)
  
(either will work). You can also access that menu at any time by running <code>netcfg-menu</code> in a terminal.
+
(either will work). And ensure that net-profiles is in your rc.conf DAEMONS array. You can also access that menu at any time by running <code>netcfg-menu</code> in a terminal.
  
 
The dialog package is needed.
 
The dialog package is needed.
  
===Automatic detection===
+
==net-auto (DEPRECATED, see net-auto-wireless)==
====net-auto====
+
 
<code>net-auto</code> is the second boot-time script of the netcfg package. Its function is to determine automatically which profile should be started.
 
<code>net-auto</code> is the second boot-time script of the netcfg package. Its function is to determine automatically which profile should be started.
  
Line 141: Line 132:
 
note: for this to work with a given profile, that profile MUST set the ESSID variable (which is not required to connect manually if a separate wpa_supplicant.conf is supplied.)
 
note: for this to work with a given profile, that profile MUST set the ESSID variable (which is not required to connect manually if a separate wpa_supplicant.conf is supplied.)
  
==Troubleshooting==
+
=Other Features=
===Wireless connections===
+
==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 put in a profile, or /etc/network.d/interfaces/$INTERFACE.
 +
 
 +
RFKILL=soft # can be either 'hard' or 'soft'.
 +
 
 +
For some kill switches the rfkill entry in /sys is not linked to the interface. For these the 'RFKILL_NAME' needs to be set. This value is the contents of the matching /sys/class/rfkill/rfkillX/name
 +
 
 +
For example on my eeepc:
 +
 
 +
RFKILL=soft
 +
RFKILL_NAME='eeepc-wlan'
 +
 
 +
==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''', '''POST_DOWN''' properties.
 +
 
 +
For example, if you want to set your wlan card to operate in ad-hoc mode but you can only change it 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;"
 +
 
 +
{{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 <nowiki>"|| true"</nowiki> to the end of the command that may fail.}}
 +
 
 +
==Profile Menu==
 +
You may select a profile to connect to from a menu. This requires the 'dialog' package installed. To display a menu, simply run 'netcfg-menu'. If you wish to have a menu on boot, set
 +
 
 +
NETWORKS=(menu)
 +
 
 +
in your /etc/rc.conf and ensure that net-profiles is in the DAEMONS array.
 +
 
 +
==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/eth0
 +
 
 +
This is useful for wpa_supplicant options, radio kill switch support, pre/post up/down scripts and net-auto-wireless. It is loaded before a profile is loaded so that any profile based options will take priority.
 +
 
 +
For example, /etc/network.d/interfaces/wlan0 may contain any valid profile option, though you're most likely going to want one of the options below. Remember that this option is set for _all_ profiles using that interface - for example you probably don't want to set your work VPN here, as it will try to connect to it on every wireless network - it would be better suited to the profile.
 +
 
 +
PRE_UP - To run a command before/after bringing the connection up/down
 +
POST_UP
 +
PRE_DOWN
 +
POST_DOWN (note only POST_UP/DOWN work with wpa_actiond)
 +
 
 +
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
 +
 
 +
==Debugging==
 +
To run netcfg with debugging output, set the NETCFG_DEBUG environment variable to "yes", for example:
 +
NETCFG_DEBUG="yes" netcfg <arguments>
 +
 
 +
=Troubleshooting=
 +
==Wireless connections==
 
For wireless connections, make sure the required drivers and firmwares are installed as explained in [[Wireless Setup]].
 
For wireless connections, make sure the required drivers and firmwares are installed as explained in [[Wireless Setup]].
===netcfg error messages===
+
==netcfg error messages==
====Network unavailable====
+
===Network unavailable===
 
This is typically one of:
 
This is typically one of:
 
* Out of range
 
* Out of range
* Driver issue (See Driver Quirks above)
+
* Driver issue  
 
* Trying to connect to a hidden network
 
* Trying to connect to a hidden network
  
Line 154: Line 206:
 
  SCAN=no  
 
  SCAN=no  
  
====Wireless Association failed====
+
===Wireless Association failed===
 
This is typically one of:
 
This is typically one of:
 
* Out of range/reception
 
* Out of range/reception
 
* Incorrect configuration
 
* Incorrect configuration
 
* Invalid key
 
* Invalid key
* Driver problem (See Driver Quirks above)
+
* Driver problem
  
 
If it is a range problem, increasing TIMEOUT= can help.
 
If it is a range problem, increasing TIMEOUT= can help.
  
====Unable to get IP address with DHCP====
+
===Unable to get IP address with DHCP===
 
This is typically one of:
 
This is typically one of:
 
* Out of range/reception
 
* Out of range/reception
Line 169: Line 221:
 
Try increasing DHCP_TIMEOUT
 
Try increasing DHCP_TIMEOUT
  
====Not a valid connection, check spelling or look at examples====
+
===Not a valid connection, check spelling or look at examples===
 
You must set CONNECTION= to one of the connection types in /usr/lib/network/connections/. Alternatively use one of the provided configuration examples in /etc/network.d/examples.
 
You must set CONNECTION= to one of the connection types in /usr/lib/network/connections/. Alternatively use one of the provided configuration examples in /etc/network.d/examples.
  
===Driver Quirks (netcfg 2.1 and later)===
+
==Driver Quirks (netcfg 2.1 and later)==
 
{{Box Note | You most likely do NOT need these. Ensure your configuration is correct before considering these. They are for a small range of drivers with unusual issues, many of them older versions. These are workarounds, not solutions. }}
 
{{Box Note | You most likely do NOT need these. Ensure your configuration is correct before considering these. They are for a small range of drivers with unusual issues, many of them older versions. These are workarounds, not solutions. }}
  
Line 188: Line 240:
  
 
If you are having problems with DNS and DHCP, try adding to your profile:
 
If you are having problems with DNS and DHCP, try adding to your profile:
  DHCLIENT=yes
+
  DHCLIENT=no
This will tell netcfg to use dhclient instead of dhcpcd(which netcfg uses by default)
+
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:
 
If you get "Wireless Network Not Found" or "Association Failed" and have tried the above, try:
 
  SCAN=no
 
  SCAN=no
  
===It still doesn't work, what do I do ?===
+
==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.  
 
If the FAQs below didn't solve your problem the next best place to go is the forums, or the mailing list.  
  
Line 206: Line 258:
 
* iwconfig
 
* iwconfig
  
==GUI==
+
=GUI=
  
 
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.
 
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.
Line 215: Line 267:
 
There is also a relatively new gui to netcfg2 on qt-apps that does only network configuring.You can find it here: [http://www.qt-apps.org/content/show.php/netcfgGUI?content=99523].
 
There is also a relatively new gui to netcfg2 on qt-apps that does only network configuring.You can find it here: [http://www.qt-apps.org/content/show.php/netcfgGUI?content=99523].
  
==Supplementary tools==
+
=Supplementary tools=
  
 
There is a console tool for selecting wireless networks "in real-time" (in NetworkManager manner) called <code>wifi-select</code>. The tool is convenient 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 <code>sudo wifi-select wlan0</code> and choose the network you need.  
 
There is a console tool for selecting wireless networks "in real-time" (in NetworkManager manner) called <code>wifi-select</code>. The tool is convenient 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 <code>sudo wifi-select wlan0</code> and choose the network you need.  
Line 231: Line 283:
 
[http://bbs.archlinux.org/viewtopic.php?id=63973 Forum thread] related to development of <code>wifi-select</code> |  [http://aur.archlinux.org/packages.php?ID=23471 wifi-select on AUR] | [http://hg.horna.org.ua/wifi-select/ wifi-select mercurial repository]
 
[http://bbs.archlinux.org/viewtopic.php?id=63973 Forum thread] related to development of <code>wifi-select</code> |  [http://aur.archlinux.org/packages.php?ID=23471 wifi-select on AUR] | [http://hg.horna.org.ua/wifi-select/ wifi-select mercurial repository]
  
==FAQ==
+
=FAQ=
===Why doesnt netcfg do ''x''?===
+
==Why doesnt netcfg do ''x''?==
 
netcfg doesn't need to. It connects to networks.
 
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.  
 
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===
+
==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'.
 
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.
 
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?===
+
==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.  
 
* /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
 
* 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.
 
* 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.
 
* lo: This is now in rc.sysinit, you don't need to configure it anywhere.
 
== Additional Resources ==
 
* http://www.rayner.id.au/netcfg/ - documentation of the supported options for 'wireless' and 'ethernet' of netcfg profile.
 
* [[Network Profiles development]] - wiki about netcfg in the [Testing] repo.
 
* [[Network Profiles with 3G card]] - how to use netcfg to connect over 3G
 

Revision as of 09:26, 18 February 2010

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

Quick Start - netcfg in 4 easy steps

Have some basic information about your wireless network ready. For a wireless network this includes what type of security is used, network name and any password or encryption keys.

netcfg is profile based. Each network has an individual profile. These profiles can be individually connected/disconnected at any time. The profile configuration varies depending on whether it's a wireless, ethernet or other type of connection. The available options are documented on the netcfg website and in the included examples.

Step 1

Ensure you have the latest version of netcfg installed. Older versions have more bugs and may not work well with the latest drivers.

# pacman -S netcfg

Step 2

Copy an example configuration from /etc/network.d/examples/ to /etc/network.d/mynetwork. The filename is the name of the network profile, "mynetwork" is used as an example throughout this quickstart. The name is not a network setting and does not need to match your wireless network name (SSID).

Depending on your security and connection, 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.

  • WEP hex key wireless-wep
  • WEP string key wireless-wep-string-key
  • WPA personal (passphrase) wireless-wpa
  • WPA enterprise wireless-wpa-config (wpa_supplicant configuration is external) or wireless-wpa-configsection (wpa_supplicant configuration stored as string)
  • Wired connection - dhcp ethernet-dhcp
  • Wired connection - static IP ethernet-static
  • Wired connection - iproute configuration ethernet-iproute

Template:Box Note

Template:Box Note

Step 3

Modify your configuration file new configuration file, /etc/network.d/mynetwork

  • Set INTERFACE= to your wireless or ethernet interface. This can be checked with ifconfig and iwconfig.
  • Make sure you set your ESSID and KEY/passphrase correctly. Typos in these are common errors.

Step 4

To connect, simply execute:

# netcfg mynetwork

To disconnect from a profile:

# netcfg down <profile-name>

If it does not work, have a look at the troubleshooting section for solutions and how to get help.

If all goes to plan, you can configure it to connect automatically or on boot.

For more command line arguments, see

# netcfg help

Configuration Notes

Using a string WEP key

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

KEY="s:Somepasskey"

Ralink legacy drivers rt2500, rt2400 that use iwpriv

There is no plans to add WPA support to these drivers. 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

Simply:

IWCONFIG="<arguments>"

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.

Connecting automatically and/or on boot

net-profiles - Connect a specific list of profiles

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

If you have nothing configured within the INTERFACES array, you may remove the "network" daemon from the daemons line.

net-auto-wireless - Automatically connect to, and roam between wireless networks

In your /etc/rc.conf, add a line setting WIRELESS_INTERFACE to your wireless device. For example:

WIRELESS_INTERFACE="wlan0"

Then add net-auto-wireless to the DAEMONS array.

This requires appropriate profiles to be made for the networks in /etc/network.d/

net-auto-wired

In your /etc/rc.conf, add a line setting WIRED_INTERFACE to your wired device. For example:

WIRED_INTERFACE="eth0"

Then add net-auto-wired to the DAEMONS array.

This requires appropriate profiles to be made for the networks in /etc/network.d/

netcfg-menu - Display a menu at boot where a profile may be selected

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:

NETWORKS=menu

or

NETWORKS=(menu)

(either will work). And ensure that net-profiles is in your rc.conf DAEMONS array. You can also access that menu at any time by running netcfg-menu in a terminal.

The dialog package is needed.

net-auto (DEPRECATED, see net-auto-wireless)

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, eg: DAEMONS=(... net-auto ...).

To run after boot:

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

note: for this to work with a given profile, that profile MUST set the ESSID variable (which is not required to connect manually if a separate wpa_supplicant.conf is supplied.)

Other Features

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 put in a profile, or /etc/network.d/interfaces/$INTERFACE.

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

For some kill switches the rfkill entry in /sys is not linked to the interface. For these the 'RFKILL_NAME' needs to be set. This value is the contents of the matching /sys/class/rfkill/rfkillX/name

For example on my eeepc:

RFKILL=soft
RFKILL_NAME='eeepc-wlan'

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, POST_DOWN properties.

For example, if you want to set your wlan card to operate in ad-hoc mode but you can only change it 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;"
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.

Profile Menu

You may select a profile to connect to from a menu. This requires the 'dialog' package installed. To display a menu, simply run 'netcfg-menu'. If you wish to have a menu on boot, set

NETWORKS=(menu) 

in your /etc/rc.conf and ensure that net-profiles is in the DAEMONS array.

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/eth0

This is useful for wpa_supplicant options, radio kill switch support, pre/post up/down scripts and net-auto-wireless. It is loaded before a profile is loaded so that any profile based options will take priority.

For example, /etc/network.d/interfaces/wlan0 may contain any valid profile option, though you're most likely going to want one of the options below. Remember that this option is set for _all_ profiles using that interface - for example you probably don't want to set your work VPN here, as it will try to connect to it on every wireless network - it would be better suited to the profile.

PRE_UP - To run a command before/after bringing the connection up/down
POST_UP
PRE_DOWN
POST_DOWN (note only POST_UP/DOWN work with wpa_actiond)
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

Debugging

To run netcfg with debugging output, set the NETCFG_DEBUG environment variable to "yes", for example: NETCFG_DEBUG="yes" netcfg <arguments>

Troubleshooting

Wireless connections

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

netcfg error messages

Network unavailable

This is typically one of:

  • Out of range
  • Driver issue
  • Trying to connect to a hidden network

If you know your network is hidden, set

SCAN=no 

Wireless Association failed

This is typically one of:

  • Out of range/reception
  • Incorrect configuration
  • Invalid key
  • Driver problem

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 one of the connection types in /usr/lib/network/connections/. Alternatively use one of the provided configuration examples in /etc/network.d/examples.

Driver Quirks (netcfg 2.1 and later)

Template:Box Note

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 (ath9k)
  • 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:

DHCLIENT=no

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:

SCAN=no

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 crucial 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 crucial as many problems are simple config issues. Feel free to censor your wireless key.
  • netcfg version
  • lsmod
  • iwconfig

GUI

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

There is also a relatively new gui to netcfg2 on qt-apps that does only network configuring.You can find it here: [1].

Supplementary tools

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 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 [community] repository. To install, do pacman -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

FAQ

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.