Difference between revisions of "Netcfg"

From ArchWiki
Jump to navigation Jump to search
m (automatic style fixes)
(netcfg was deprecated in favour of netctl, just redirect there)
(127 intermediate revisions by 44 users not shown)
Line 1: Line 1:
{{Lowercase title}}
#REDIRECT [[Netctl]]
{{Article summary start}}
{{Article summary text|A guide to installing and configuring netcfg – network configuration and profile scripts.}}
{{Article summary heading|Overview}}
{{Article summary text|{{Networking overview}}}}
{{Article summary heading|Resources}}
{{Article summary link|netcfg network scripts repository|https://projects.archlinux.org/netcfg.git/}}
{{Article summary end}}
From the [https://projects.archlinux.org/netcfg.git/tree/docs/netcfg.txt 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.
In the simplest cases, users must at least know the name of their network interface(s) (e.g. {{ic|eth0}}, {{ic|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]].
Ensure you have the latest version of {{Pkg|netcfg}} installed. Older versions have more bugs and may not work well with the latest drivers. The {{Pkg|netcfg}} package is available in the [[Official Repositories|official repositories]].
As of {{Pkg|netcfg}} version 2.5.x, optional dependencies include {{Pkg|wpa_actiond}} – required for automatic/roaming wireless connections – and {{Pkg|ifplugd}} – required for automatic Ethernet configuration. ([https://www.archlinux.org/news/487/ More information].)
If you want to have [[Bash]] completion support for netcfg, install the {{Pkg|bash-completion}} package from the official repositories.
Network profiles are stored in the {{ic|/etc/network.d}} directory. To minimize the potential for errors, copy an example configuration from {{ic|/etc/network.d/examples/}} to {{ic|/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 {{ic|/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.
{| border="1"
! Connection type/security !! Example profile
| Wireless; WEP hex key || {{ic|wireless-wep}}
| Wireless; WEP string key || {{ic|wireless-wep-string-key}}
| Wireless; WPA-Personal (passphrase/pre-shared key) || {{ic|wireless-wpa}}
| Wireless; WPA-Enterprise || {{ic|wireless-wpa-config}} (wpa_supplicant configuration is external) <br /> {{ic|wireless-wpa-configsection}} (wpa_supplicant configuration stored as string)
| Wired; DHCP || {{ic|ethernet-dhcp}}
| Wired; static IP || {{ic|ethernet-static}}
| Wired; iproute configuration || {{ic|ethernet-iproute}}
Next, modify the new configuration file, {{ic|/etc/network.d/mynetwork}}:
* Set {{ic|INTERFACE}} to the correct wireless or Ethernet interface. This can be checked with {{ic|ip link}} and {{ic|iwconfig}}.
* Ensure the {{ic|ESSID}} and {{ic|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 {{ic|s:}} (e.g. {{ic|<nowiki>KEY="s:somepasskey"</nowiki>}}).
{{Note|netcfg configurations are valid Bash scripts. Any configuration involving special characters such as {{ic|$}} or {{ic|\}} 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. {{ic|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#Classic_method:_.2Fetc.2Fwpa_supplicant.conf|WPA supplicant page's first example exercise]] to generate a hexadecimal string from you WPA passkey.<br />
Save the new hexadecimal string into your wireless WPA profile in {{ic|/etc/network.d/mynetwork}} as the value of the {{ic|KEY}} variable (make sure this will be the only {{ic|KEY}} variable enabled), to look similar to this (replace the string with your one):
That should do it, without the need to reveal the passkey.<br />
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
==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 {{ic|/etc/network.d}} directory ''first'' (see [[#Configuration]]).
{{Tip|If enabling one of the following daemons and nothing is configured within the {{ic|INTERFACES}} array in {{ic|/etc/rc.conf}}, you may remove the {{ic|network}} daemon from the {{ic|DAEMONS}} array. If you mount [[NFS]] shares during boot, ensure the {{ic|netfs}} daemon remains listed, though (otherwise the network will be dropped before unmounting shares during shutdown).}}
'''{{ic|net-profiles}} allows users to connect profiles during boot.'''
To enable this feature, users must add {{ic|net-profiles}} to the {{ic|DAEMONS}} array in {{ic|/etc/[[rc.conf]]}} and specify profiles to try in the {{ic|NETWORKS}} array:
NETWORKS=(mynetwork yournetwork)
DAEMONS=(... net-profiles ...)
Alternatively, {{ic|net-profiles}} can be configured to display a menu &ndash; allowing users to choose a desired profile &ndash; by setting the contents of the {{ic|NETWORKS}} array to {{ic|menu}}:
DAEMONS=(... net-profiles ...)
Additionally, the {{Pkg|dialog}} package is required.
{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}
'''{{ic|net-auto-wireless}} allows users to automatically connect to wireless networks with proper roaming support.'''
To enable this feature, users must add {{ic|net-auto-wireless}} to the {{ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:
DAEMONS=(... net-auto-wireless ...)
And specify the desired wireless interface with the {{ic|WIRELESS_INTERFACE}} variable:
In {{ic|/etc/conf.d/netcfg}} it is also possible to define a list of wireless networks that should be automatically connected, if no such list is used, all wireless networks will be tried.
Additionally, the {{Pkg|wpa_actiond}} package is required. Note that {{ic|wireless-wpa-config}} profiles do not work with {{ic|net-auto-wireless}}. Convert them to {{ic|wireless-wpa-configsection}} instead.
'''{{ic|net-auto-wired}} allows users to automatically connect to wired networks.'''
To enable this feature, users must [[pacman|install]] {{Pkg|ifplugd}}, then add {{ic|net-auto-wired}} to the {{ic|DAEMONS}} array in {{ic|/etc/rc.conf}} and specify the desired wired interface with the {{ic|WIRED_INTERFACE}} variable:
DAEMONS=(... net-auto-wired ...)
The daemon starts an {{ic|ifplugd}} process which runs {{ic|/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 {{ic|CONNECTION <nowiki>=</nowiki> "ethernet"}} or {{ic|"ethernet-iproute"}} and {{ic|INTERFACE <nowiki>=</nowiki> 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 {{ic|1=AUTO_WIRED=1}} to the desired profile.}}
{{Note|The {{ic|net-auto-wired}} daemon cannot start multiple ifplugd processes for multiple interfaces (unlike ifplugd's own {{ic|/etc/rc.d/ifplugd}} which can).}}
==Tips and tricks==
===Passing arguments to iwconfig before connecting===
Simply add the following to a profile:
Where {{ic|<arguments>}} can be any valid {{ic|iwconfig}} argument. The script then runs {{ic|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 {{ic|IWOPTS}} and {{ic|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 ({{ic|/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 {{ic|/sys}} is not linked to the interface and the {{ic|RFKILL_NAME}} variable needs to be set to the contents of the matching {{ic|/sys/class/rfkill/rfkill#/name}}.
For example, on an Eee PC:
On a mid-2011 Thinkpad:
{{Note|The {{ic|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 {{Ic|/sys/class/rfkill/rfkill#}} entries with different names on every switch. Something like this will work in such cases (wifi-only solution!):
RFKILL_NAME=`cat /sys/class/rfkill/rfkill*/name 2> /dev/null || echo ""`</nowiki>}}}}
===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 {{ic|PRE_UP}}, {{ic|POST_UP}}, {{ic|PRE_DOWN}}, and {{ic|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 {{ic|exit 0}} at the end. Alternatively you can add {{ic|<nowiki>|| true</nowiki>}} 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:
log() { logger -t "$( basename $0 )" "$*" ; }
main() {
        local host
        while sleep 1; do
                [[ "$( netcfg current )" = "" ]] && continue
                host=$( route -n | awk '/^ { print $2 }' )
                ping -c 1 $host && continue
                log "trying to reassociate"
                wpa_cli reassociate
                ping -c 1 $host && continue
                log "reassociate failed, reconfiguring network"
                netcfg -r $( netcfg current )
exec 1>/dev/null
[[ $EUID != 0 ]] && { log "must be root"; exit 1; }
for cmd in wpa_cli ping netcfg; do
        ! which $cmd && {
                log "can't find command ${cmd}, exiting..."
                exit 1
log 'starting...'
===Per-interface configuration===
Configuration options that apply to all profiles using an interface can be set using {{ic|/etc/network.d/interfaces/$INTERFACE}}. For example:
This is useful for {{ic|wpa_supplicant}} options, rfkill switch support, pre/post up/down scripts and {{ic|net-auto-wireless}}. These options are loaded ''before'' profiles so that any profile-based options will take priority.
{{ic|/etc/network.d/interfaces/$INTERFACE}} may contain any valid profile option, though you are likely to use {{ic|PRE_UP}}/{{ic|DOWN}} and {{ic|POST_UP}}/{{ic|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
{{Note|{{ic|POST_UP}}/{{ic|POST_DOWN}} require the {{Pkg|wpa_actiond}} package.}}
===Output hooks===
netcfg has limited support to load hooks that handle output. By default it loads the {{ic|arch}} hook which provides the familiar output that you see. A syslog logging hook is also included. These can be found at {{ic|/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.
* {{AUR|archassistant}} in the [[Arch User Repository|AUR]]
* [http://www.kde-apps.org/content/show.php/ArchAssistant?content=76760 archassistant on kde-apps.org]
There is also a relatively new GUI for netcfg on qt-apps.org that does only network configuration. You can find it [http://www.qt-apps.org/content/show.php/netcfgGUI?content=99523 here].
There is a console tool for selecting wireless networks in "real-time" (in [[NetworkManager]] fashion) called {{Pkg|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 {{ic|wifi-select wlan0}} as root and choose the desired network.
The tool is currently packaged as {{Pkg|wifi-select}} and is available in the [[Official Repositories|official repositories]].
{{Pkg|wifi-select}} does the following:
* parses {{ic|iwlist scan}} results and presents a list of networks along with their security settings (WPA/WEP/none) using {{Pkg|dialog}}
* if user selects network with existing profile -- just use this profile to connect with {{Pkg|netcfg}}
* if user selects a new network (for example, a Wi-Fi hotspot), {{Pkg|wifi-select}} automatically generates a new profile with corresponding {{ic|$SECURITY}} and asks for the key (if needed). It uses DHCP as {{ic|$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 {{ic|$IP}} to static or adjust some additional options)
* [https://bbs.archlinux.org/viewtopic.php?id=63973 Forum thread] related to development of {{Pkg|wifi-select}}
* [http://hg.horna.org.ua/wifi-select/ wifi-select Mercurial repository]
* [https://github.com/sphynx/wifi-select wifi-select on GitHub]
{{Note|Latest version of netcfg will provide '''wifi-menu''' with functionality equal to that of wifi-select.}}
===Passing arguments to dhcpcd===
For example, add
DHCP_OPTIONS='-C resolv.conf -G'
to the desired profile. The above example prevents {{Pkg|dhcpcd}} from writing to {{ic|/etc/resolv.conf}} and setting any default routes.
===Using dhclient instead of dhcpcd===
To use {{Pkg|dhclient}} instead of {{Pkg|dhcpcd}}, simply add {{ic|DHCLIENT<nowiki>=</nowiki>yes}} to the desired profile.
===Configuring a bridge for use with virtual machines (VMs)===
To configure a bridge named br0 with a static IP:
DESCRIPTION="bridge br0 static"
To configure a bridge named br0 with a dhcp IP:
DESCRIPTION="bridge br0 dhcp"
Then add the corresponding bridge name to your {{ic|NETWORKS&#61;(...)}} in {{ic|/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 {{ic|ip}} command in a {{ic|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 {{ic|;}}. So if you for example would want to assign both and to interface eth0; the config would look something among the lines of:
POST_UP='ip addr add dev eth0'
===Adding static routes===
When wanting to configure static routes, this can be done by issuing the relevant {{ic|ip}} command in a {{ic|POSTUP}} statement (which as the name suggests will be executed after the interface has been brought up). Optionally, a {{ic|PRE_DOWN}} statement can be added to remove said routes when the interface is brought down. Multiple statements can be separated with a {{ic|;}}. In the below example we'll route over interface eth1 and then remove the route when the interface is brought down.
POST_UP='ip route add dev eth1'
PRE_DOWN='ip route del dev eth1'
To run netcfg with debugging output, set the {{ic|NETCFG_DEBUG}} environment variable to {{ic|"yes"}}, for example:
# NETCFG_DEBUG="yes" netcfg <arguments>
Debugging information for wpa_supplicant can be logged using {{ic|WPA_OPTS}} within a profile, for example:
Whatever is entered here will be added to the command when {{ic|wpa_supplicant}} is called.
===Network unavailable===
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 the connection problem is due to poor reception, increase the {{ic|TIMEOUT}} variable in {{ic|/etc/network.d/mynetwork}}, such as:
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
Try increasing {{ic|DHCP_TIMEOUT}} variable in your network {{ic|/etc/network.d/profile}}.
===Not a valid connection, check spelling or look at examples===
You must set {{ic|CONNECTION}} to one of the connection types listed in the {{ic|/usr/lib/network/connections}} directory. Alternatively, use one of the provided configuration examples in {{ic|/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.
  DEBUG: Loading profile eth0-dhcp
  DEBUG: Configuring interface eth0
  :: eth0-dhcp up
  DEBUG: status reported to profile_up as:
  DEBUG: Loading profile eth0-dhcp
  DEBUG: Configuring interface eth0
  DEBUG: ethernet_iproute_up ifup
    > No connection
  DEBUG: profile_up connect failed
The default is 2 seconds.
To lengthen the timeout, set the CARRIER_TIMEOUT variable before calling netcfg.
This thread shows one example of this issue:
===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.
; {{ic|prescan}}: Run {{ic|iwlist $INTERFACE scan}} before attempting to connect (Broadcom)
; {{ic|preessid}}: Run {{ic|iwconfig $INTERFACE essid $ESSID}} before attempting to connect (ipw3945, Broadcom and Intel PRO/Wireless 4965AGN)
; {{ic|wpaessid}}: Same as previous, run before starting {{ic|wpa_supplicant}}. Not supported anymore  - use {{ic|1=IWCONFIG="essid $ESSID"}} instead. (ath9k)
; {{ic|predown}}: Take interface down before association and then restore it after (madwifi)
; {{ic|postsleep}}: Sleep one second before checking if the association was successful
; {{ic|postscan}}: Run {{ic|iwlist scan}} after associating
Add the required quirks to the netcfg configuration file {{ic|/etc/network.d/mynetwork}}, for example:
QUIRKS=(prescan preessid)
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]].
===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 {{ic|iwpriv}} commands and put its path in {{ic|PRE_UP}}.
===find: "/var/run/network//suspend/":  No such file or directory===
If you get this error message, then do not bother because it is a known bug. Create the directory by hand.
===It still does not work, what do I do?===
If this article did not help solve your problem, the next best places to ask for help are the forums, the mailing list, and the #archlinux IRC channel.
To be able to determine the problem, we need information. When you ask, provide the following output:
* '''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.
* '''{{ic|/etc/network.d}} network profiles'''
** This is also crucial as many problems are simple configuration issues. Feel free to censor your wireless key.
* '''netcfg version'''
* {{ic|lsmod}}
* {{ic|iwconfig}}
|question=Why doesn't netcfg do ''(some feature)''?
|answer=netcfg does not need to; it connects to networks. netcfg is modular and re-usable; see {{ic|/usr/lib/network}} for re-usable functions for custom scripts.}}
|question=Why doesn't netcfg behave in ''this'' way?
|answer=netcfg does not enforce any rules; it connects to networks. netcfg does not impose any heuristics, like "disconnect from wireless if Ethernet is connected". If you want behavior like that, it should be simple to write a separate tool on top of netcfg. See the question above.}}
|question=Do I still need ''(some thing)'' if I am using netcfg?
|answer=This question usually references {{ic|/etc/hosts}} and the {{ic|HOSTNAME}} variable in {{ic|/etc/rc.conf}}, which are both still required. You may remove {{ic|network}} from the {{ic|DAEMONS}} array if you have configured all of your networks with netcfg, though.}}

Latest revision as of 15:26, 16 July 2013

Redirect to: