Network Profiles development
From ArchWiki
Contents |
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 -Sy 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
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;"
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)
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) usingdialog
- 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.