Difference between revisions of "Netcfg"

From ArchWiki
Jump to: navigation, search
(Configuration)
m
(46 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
{{Lowercase title}}
 
{{Lowercase title}}
 
[[Category:Networking]]
 
[[Category:Networking]]
 +
[[es:Netcfg]]
 
[[fr:Netcfg]]
 
[[fr:Netcfg]]
 
[[it:Netcfg]]
 
[[it:Netcfg]]
Line 8: Line 9:
 
[[zh-CN:Netcfg]]
 
[[zh-CN:Netcfg]]
 
{{Article summary start}}
 
{{Article summary start}}
{{Article summary text|A guide to installing and configuring netcfg – network configuration and profile scripts.}}
+
{{Article summary text|A guide to configuring the network using netcfg and network profile scripts.}}
 
{{Article summary heading|Overview}}
 
{{Article summary heading|Overview}}
 
{{Article summary text|{{Networking overview}}}}
 
{{Article summary text|{{Networking overview}}}}
 
{{Article summary heading|Resources}}
 
{{Article summary heading|Resources}}
{{Article summary link|netcfg network scripts repository|https://projects.archlinux.org/netcfg.git/}} - Git repo for official package scripts.
+
{{Article summary wiki|Netcfg Tips}}
{{Article summary wiki|Netcfg_Tips}} - Tips and Tricks for netcfg.
+
{{Article summary wiki|Netcfg Troubleshooting}}
 +
{{Article summary link|Netcfg network scripts repository|https://projects.archlinux.org/netcfg.git/}}
 
{{Article summary end}}
 
{{Article summary end}}
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.  Further it is useful for users seeking a simple and robust means of managing multiple network configurations (e.g. laptop users). With the push to drop support for initscripts/sysv, netcfg is one of several choices users have to managing their network connectivity under systemd.
 
  
{{Note|netcfg-2.8.9 drops deprecated rc.conf compatibility. Users of netcfg should configure all interfaces in {{ic|/etc/conf.d/netcfg}} rather than {{ic|/etc/rc.conf}}.}}
+
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 and [[Wikipedia:Point-to-point_protocol|PPP]]. It is also capable of starting/stopping many-to-one connections, that is, multiple connections within the same profile, optionally with bonding. Further it is useful for users seeking a simple and robust means of managing multiple network configurations (e.g. laptop users). With the push to drop support for {{Pkg|initscripts}}/SysV, netcfg is one of several choices users have to managing their network connectivity under [[systemd]].
==Preparation==
+
 
 +
{{Note|1={{Pkg|netcfg}} >= 2.8.9 drops deprecated {{ic|/etc/[[rc.conf]]}} compatibility. Netcfg users should configure all interfaces in {{ic|/etc/conf.d/netcfg}} instead of {{ic|/etc/rc.conf}}.}}
 +
 
 +
== Preparation ==
 +
 
 
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.
 
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]].
+
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 passphrase or encryption keys. Additionally, ensure the proper drivers and firmware are installed for the wireless device, as described in [[Wireless Setup]].
  
==Installation==
+
== Installation ==
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].)
+
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}}, which is required for automatic/roaming wireless connections, and {{Pkg|ifplugd}}, which is required for automatic Ethernet configuration. See [https://www.archlinux.org/news/487/ the announcement].
  
 
Users wanting [[Bash]] completion support for netcfg, install the {{Pkg|bash-completion}} package from the official repositories.
 
Users wanting [[Bash]] completion support for netcfg, install the {{Pkg|bash-completion}} package from the official repositories.
  
==Configuration==
+
== Configuration ==
Network profiles are stored in {{ic|/etc/network.d}}.
+
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.  
+
Network profiles are stored in {{ic|/etc/network.d/}}. 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, and {{ic|mynetwork}} is used as an example throughout this article.
  
=== Wireless Example ===
+
Depending on the connection type and security, use one of the following examples from {{ic|/etc/network.d/examples/}} as a base.
{{Warning|Be wary of examples found on the Internet as they often contain deprecated options that may cause problems!}}
+
  
{| border="1"
+
{{Warning|Be wary of examples found on the internet as they often contain deprecated options that may cause problems!}}
! Connection type/security !! Example profile
+
 
 +
{| class="wikitable" align="center"
 +
! Connection !! Type !! Example Profile !! Information
 
|-
 
|-
| Wireless; WEP hex key || {{ic|wireless-wep}}
+
| rowspan="3"| '''Wired'''
 +
| Dynamic IP || {{ic|ethernet-dhcp}} ||
 
|-
 
|-
| Wireless; WEP string key || {{ic|wireless-wep-string-key}}
+
| Static IP || {{ic|ethernet-static}} ||
 
|-
 
|-
| Wireless; WPA-Personal (passphrase/pre-shared key) || {{ic|wireless-wpa}}
+
| Routed || {{ic|ethernet-iproute}} || Can be checked with {{ic|route}} from the {{Pkg|net-tools}} package.
 
|-
 
|-
| Wireless; WPA-Enterprise || {{ic|wireless-wpa-config}} (wpa_supplicant configuration is external) <br /> {{ic|wireless-wpa-configsection}} (wpa_supplicant configuration stored as string)
+
| rowspan="3"| '''Wireless'''
 +
| WPA-Personal
 +
| {{ic|wireless-wpa}} || Uses a passphrase/pre-shared key.
 
|-
 
|-
| Wired; DHCP || {{ic|ethernet-dhcp}}
+
| rowspan="2"| WPA-Enterprise
 +
| {{ic|wireless-wpa-config}} || The {{Pkg|wpa_supplicant}} configuration is external.
 
|-
 
|-
| Wired; static IP || {{ic|ethernet-static}}
+
| {{ic|wireless-wpa-configsection}} || The {{Pkg|wpa_supplicant}} configuration is stored as a string.
|-
+
| Wired; iproute configuration || {{ic|ethernet-iproute}}
+
 
|}
 
|}
  
Line 61: Line 66:
 
* Set {{ic|INTERFACE}} to the correct wireless or Ethernet interface. This can be checked with {{ic|ip link}} and {{ic|iwconfig}}.
 
* 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.
 
* 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 that WEP ''string'' keys (not ''hex'' keys) must be specified with a leading {{ic|s:}} (e.g. {{ic|1=KEY="s:''somepasskey''"}}).
  
{{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|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|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.
+
{{Note|For WPA-Personal, it is also possible to [[Wpa_supplicant#Classic_method:_.2Fetc.2Fwpa_supplicant.conf|encode the WPA passkey into a hexadecimal string]]. Save the new hexadecimal string into the 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: {{ic|1=KEY='7b271c9a7c8a6ac07d12403a1f0792d7d92b5957ff8dfd56481ced43ec6a6515'}}. That should disable the need to reveal the 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 the 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:
+
== Manual Operation ==
KEY<nowiki>=</nowiki>'7b271c9a7c8a6ac07d12403a1f0792d7d92b5957ff8dfd56481ced43ec6a6515'
+
That should do it, without the need to reveal the passkey.<br />
+
}}
+
  
==Manual Operation==
 
 
To connect a profile:
 
To connect a profile:
 +
 
  # netcfg mynetwork
 
  # netcfg mynetwork
  
 
To disconnect a profile:
 
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.
+
# netcfg down mynetwork
 +
 
 +
If successful, users can configure netcfg to connect automatically or during boot. If the connection fails, see [[Netcfg Troubleshooting]] for solutions and for how to ask for help.
 +
 
 +
Additionally, see:
  
For other functions, see:
 
 
  $ netcfg help
 
  $ netcfg help
  
 
== Automatic Operation ==
 
== Automatic Operation ==
===Systemd Support (Recommended) ===
 
Since version 2.8.2 {{Pkg|netcfg}} provides systemd unit files. The service files {{ic|net-auto-wireless.service}} and {{ic|net-auto-wired.service}} correspond to the {{Pkg|initscripts}} daemons {{ic|/etc/rc.d/net-auto-wireless}} and {{ic|/etc/rc.d/net-auto-wired}}. To connect to multiple profiles at boot, use {{ic|netcfg.service}} which is equivalent to {{ic|/etc/rc.d/net-profiles}} and starts all profiles specified in the {{ic|NETWORKS}} array in {{ic|/etc/conf.d/netcfg}}. These service files can be enabled and started with {{ic|systemctl}} as usual.
 
  
There are explained in the legacy section referring to the soon to be  depreciated /etc/rc.conf methods below.
+
=== Just one profile ===
  
Alternatively, use the template service file {{ic|netcfg@.service}} that allows connection to a profile on boot without having to specify it in {{ic|/etc/conf.d/netcfg}}. To specify the desired profile, enable the template service and use the network profile name as the instance name:
+
In the simplest case, only one profile will be used and is always desired to start on boot:
# systemctl enable netcfg@<profile-name>.service
+
  
=== SysV Support (Soon to be Depreciated/Legacy) ===
+
# systemctl enable netcfg@myprofile
====Net-Profiles====
+
'''{{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 in {{ic|/etc/conf.d/netcfg}}:
+
=== Net-Profiles ===
  
{{hc|/etc/rc.conf|<nowiki>
+
Edit the {{ic|NETWORKS}} array in {{ic|/etc/conf.d/netcfg}} to refer to the network config file {{ic|/etc/network.d/mynetwork}}.
DAEMONS=(... net-profiles ...)
+
</nowiki>}}
+
{{hc|/etc/conf.d/netcfg|<nowiki>
+
NETWORKS=(mynetwork yournetwork)
+
</nowiki>}}
+
A network profile can also be started in the background by prefixing it with a {{ic|@}} in the {{ic|NETWORKS}} array. Note that one should only do this if the backgrounded profiles configure separate interfaces, otherwise race conditions may occur.
+
  
{{hc|/etc/conf.d/netcfg|<nowiki>
+
{{hc|/etc/conf.d/netcfg|2=
NETWORKS=(@mynetwork @yournetwork)
+
NETWORKS=(mynetwork yournetwork)}}
</nowiki>}}
+
  
Alternatively, {{ic|net-profiles}} can be configured to restore the profiles that were active at last shutdown by setting the {{ic|NETWORKS}} array to {{ic|last}}, as described below.
+
Start the service on startup:
  
{{hc|/etc/conf.d/netcfg|<nowiki>
+
# systemctl enable netcfg
NETWORKS=(last)
+
</nowiki>}}
+
  
Finally, {{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}}:
+
Alternatively, the profiles that were active at last shutdown can be restored by setting the {{ic|NETWORKS}} array to {{ic|last}}.
  
{{hc|/etc/conf.d/netcfg|<nowiki>
+
{{hc|/etc/conf.d/netcfg|2=
NETWORKS=(menu)
+
NETWORKS=(last)}}
</nowiki>}}
+
  
Additionally, the {{Pkg|dialog}} package is required.
+
{{Note|For {{ic|NETWORKS&#61;(last)}} to work, you will have to connect to your network manually first and then stop the daemon for Netcfg to remember the network. You can stop the Netcfg daemon by running {{ic|netcfg-daemon stop}} as root.}}
  
{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}
+
Finally, {{ic|net-profiles}} can be configured to display a menu&mdash;allowing users to choose a desired profile&mdash;by setting the contents of the {{ic|NETWORKS}} array to {{ic|menu}}:
  
====Net-Auto-Wireless====
+
{{hc|/etc/conf.d/netcfg|2=
'''{{ic|net-auto-wireless}} allows users to automatically connect to wireless networks with proper roaming support.'''
+
NETWORKS=(menu)}}
  
To enable this feature, users must add {{ic|net-auto-wireless}} to the {{ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:
+
Additionally, the {{Pkg|dialog}} package is required.
{{hc|/etc/rc.conf|<nowiki>
+
DAEMONS=(... net-auto-wireless ...)
+
</nowiki>}}
+
  
And specify the desired wireless interface with the {{ic|WIRELESS_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}}:
+
{{Note|The {{ic|1=NETWORKS=(menu)}} setting cannot be used anymore when switching to systemd. See {{bug|31377}} for details.}}
  
{{hc|/etc/conf.d/netcfg|<nowiki>
+
{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}
WIRELESS_INTERFACE="wlan0"
+
</nowiki>}}
+
  
It is also possible to define a list of wireless networks that should be automatically connected with the {{ic|AUTO_PROFILES}} variable in  {{ic|/etc/conf.d/netcfg}}. If {{ic|AUTO_PROFILES}} is not set, all wireless networks will be tried.
+
=== Net-Auto-Wireless ===
  
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.
+
This allows users to automatically connect to wireless networks with proper roaming support. To use this feature, 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.
  
====Net-Auto-Wired====
+
Specify the desired wireless interface with the {{ic|WIRELESS_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}} or define a list of wireless networks that should be automatically connected with the {{ic|AUTO_PROFILES}} variable in {{ic|/etc/conf.d/netcfg}}.
'''{{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 in {{ic|/etc/conf.d/netcfg}}:
+
{{Note|If AUTO_PROFILES is not set, all wireless networks will be tried.}}
  
{{hc|/etc/rc.conf|<nowiki>
+
Enable {{ic|net-auto-wireless.service}} so systemd manages it.
DAEMONS=(... net-auto-wired ...)
+
</nowiki>}}
+
{{hc|/etc/conf.d/netcfg|<nowiki>
+
WIRED_INTERFACE="eth0"
+
</nowiki>}}
+
  
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.
+
# systemctl enable net-auto-wireless
  
{{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.}}
+
=== Net-Auto-Wired ===
  
{{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).}}
+
This allows users to automatically connect to wired networks. To use this feature, the {{Pkg|ifplugd}} package is required.
  
==Troubleshooting==
+
Specify the desired wired interface with the {{ic|WIRED_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}}.
  
===Debugging===
+
Enable {{ic|net-auto-wired.service}} so systemd manages it.
To run netcfg with debugging output, set the {{ic|NETCFG_DEBUG}} environment variable to {{ic|"yes"}}, for example:
+
  
  # NETCFG_DEBUG="yes" netcfg <arguments>
+
  # systemctl enable net-auto-wired
  
Debugging information for wpa_supplicant can be logged using {{ic|WPA_OPTS}} within a profile, for example:
+
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|1=CONNECTION = "ethernet"}} or {{ic|"ethernet-iproute"}} and {{ic|1=INTERFACE = WIRED_INTERFACE}} until one of them succeeds.
  
WPA_OPTS="-f/path/to/log"
+
{{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.}}
  
Whatever is entered here will be added to the command when {{ic|wpa_supplicant}} is called.
+
{{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).}}
 
+
===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:
+
TIMEOUT=60
+
 
+
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===
+
====Carrier Timeout====
+
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
+
  [FAIL]
+
 
+
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:
+
https://bbs.archlinux.org/viewtopic.php?id=138615
+
 
+
====Skip no carrier====
+
When you can manually bring up an interface but the journal says „No connection“ during boot, it might be that the physical connection cannot be detected fast enough. Try adding
+
 
+
  SKIPNOCARRIER='yes'
+
 
+
to your profile. Netcfg will then assign the IP address regardless of whether there is a cable actually attached.
+
 
+
===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:
+
== FAQ ==
* '''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}}
+
  
==FAQ==
 
 
{{FAQ
 
{{FAQ
 
|question=Why doesn't netcfg do ''(some feature)''?
 
|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.}}
+
|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.}}
  
 
{{FAQ
 
{{FAQ
 
|question=Why doesn't netcfg behave in ''this'' way?
 
|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.}}
+
|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 such behavior, it should be simple to write a separate tool on top of netcfg. See the question above. Alternatively, you could be creative with the use of netcfg's {{ic|POST_UP}} functionality to handle some use cases.}}
  
 
{{FAQ
 
{{FAQ
|question=Do I still need ''(some thing)'' if I am using netcfg?
+
|question=Do I need anything else if I'm 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.}}
+
|answer=This question usually references {{ic|/etc/hosts}} and {{ic|/etc/hostname}}, which are both still required.}}

Revision as of 21:50, 12 November 2012

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary link Template:Article summary end

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 and PPP. It is also capable of starting/stopping many-to-one connections, that is, multiple connections within the same profile, optionally with bonding. Further it is useful for users seeking a simple and robust means of managing multiple network configurations (e.g. laptop users). With the push to drop support for initscripts/SysV, netcfg is one of several choices users have to managing their network connectivity under systemd.

Note: netcfg >= 2.8.9 drops deprecated /etc/rc.conf compatibility. Netcfg users should configure all interfaces in /etc/conf.d/netcfg instead of /etc/rc.conf.

Preparation

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, 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 passphrase or encryption keys. Additionally, ensure the proper drivers and firmware are installed for the wireless device, as described in Wireless Setup.

Installation

The netcfg package is available in the official repositories. As of netcfg version 2.5.x, optional dependencies include wpa_actiond, which is required for automatic/roaming wireless connections, and ifplugd, which is required for automatic Ethernet configuration. See the announcement.

Users wanting Bash completion support for netcfg, install the bash-completion package from the official repositories.

Configuration

Network profiles are stored in /etc/network.d/. To minimize the potential for errors, copy an example configuration from /etc/network.d/examples/ to /etc/network.d/mynetwork. The file name is the name of the network profile, and mynetwork is used as an example throughout this article.

Depending on the connection type and security, use one of the following examples from /etc/network.d/examples/ as a base.

Warning: Be wary of examples found on the internet as they often contain deprecated options that may cause problems!
Connection Type Example Profile Information
Wired Dynamic IP ethernet-dhcp
Static IP ethernet-static
Routed ethernet-iproute Can be checked with route from the net-tools package.
Wireless WPA-Personal wireless-wpa Uses a passphrase/pre-shared key.
WPA-Enterprise wireless-wpa-config The wpa_supplicant configuration is external.
wireless-wpa-configsection The wpa_supplicant configuration is stored as a string.

Modify the new configuration file, /etc/network.d/mynetwork:

  • Set INTERFACE to the correct wireless or Ethernet interface. This can be checked with ip link and iwconfig.
  • Ensure the ESSID and 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 s: (e.g. KEY="s:somepasskey").
Note: Netcfg configurations are valid Bash scripts. Any configuration involving special characters such as $ or \ 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. chmod 0600 /etc/network.d/mynetwork) to make it readable by root only.
Note: For WPA-Personal, it is also possible to encode the WPA passkey into a hexadecimal string. Save the new hexadecimal string into the wireless WPA profile in /etc/network.d/mynetwork as the value of the KEY variable (make sure this will be the only KEY variable enabled), to look similar to this: KEY='7b271c9a7c8a6ac07d12403a1f0792d7d92b5957ff8dfd56481ced43ec6a6515'. That should disable the need to reveal the passkey.

Manual Operation

To connect a profile:

# netcfg mynetwork

To disconnect a profile:

# netcfg down mynetwork

If successful, users can configure netcfg to connect automatically or during boot. If the connection fails, see Netcfg Troubleshooting for solutions and for how to ask for help.

Additionally, see:

$ netcfg help

Automatic Operation

Just one profile

In the simplest case, only one profile will be used and is always desired to start on boot:

# systemctl enable netcfg@myprofile

Net-Profiles

Edit the NETWORKS array in /etc/conf.d/netcfg to refer to the network config file /etc/network.d/mynetwork.

/etc/conf.d/netcfg
NETWORKS=(mynetwork yournetwork)

Start the service on startup:

# systemctl enable netcfg

Alternatively, the profiles that were active at last shutdown can be restored by setting the NETWORKS array to last.

/etc/conf.d/netcfg
NETWORKS=(last)
Note: For NETWORKS=(last) to work, you will have to connect to your network manually first and then stop the daemon for Netcfg to remember the network. You can stop the Netcfg daemon by running netcfg-daemon stop as root.

Finally, net-profiles can be configured to display a menu—allowing users to choose a desired profile—by setting the contents of the NETWORKS array to menu:

/etc/conf.d/netcfg
NETWORKS=(menu)

Additionally, the dialog package is required.

Note: The NETWORKS=(menu) setting cannot be used anymore when switching to systemd. See FS#31377 for details.
Tip: Access the menu at any time by running netcfg-menu in a terminal.

Net-Auto-Wireless

This allows users to automatically connect to wireless networks with proper roaming support. To use this feature, the wpa_actiond package is required. Note that wireless-wpa-config profiles do not work with net-auto-wireless. Convert them to wireless-wpa-configsection instead.

Specify the desired wireless interface with the WIRELESS_INTERFACE variable in /etc/conf.d/netcfg or define a list of wireless networks that should be automatically connected with the AUTO_PROFILES variable in /etc/conf.d/netcfg.

Note: If AUTO_PROFILES is not set, all wireless networks will be tried.

Enable net-auto-wireless.service so systemd manages it.

# systemctl enable net-auto-wireless

Net-Auto-Wired

This allows users to automatically connect to wired networks. To use this feature, the ifplugd package is required.

Specify the desired wired interface with the WIRED_INTERFACE variable in /etc/conf.d/netcfg.

Enable net-auto-wired.service so systemd manages it.

# systemctl enable net-auto-wired

The daemon starts an ifplugd process which runs /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 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. However, one can tell netcfg to prefer a particular interface by adding AUTO_WIRED=1 to the desired profile.
Note: The net-auto-wired daemon cannot start multiple ifplugd processes for multiple interfaces (unlike ifplugd's own /etc/rc.d/ifplugd which can).

FAQ

Template:FAQ

Template:FAQ

Template:FAQ