Difference between revisions of "Netcfg"

From ArchWiki
Jump to: navigation, search
(Net-Profiles)
(netcfg was deprecated in favour of netctl, just redirect there)
 
(68 intermediate revisions by 27 users not shown)
Line 1: Line 1:
{{Lowercase title}}
+
#REDIRECT [[Netctl]]
[[Category:Networking]]
+
[[fr:Netcfg]]
+
[[it:Netcfg]]
+
[[ro:Netcfg]]
+
[[ru:Netcfg]]
+
[[tr:netcfg]]
+
[[zh-CN:Netcfg]]
+
{{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 wiki|Netcfg_Tips}} - Tips and Tricks for netcfg.
+
{{Article summary wiki|Netcfg_Troubleshooting}} - Troubleshooting for netcfg.
+
{{Article summary link|Netcfg network scripts repository|https://projects.archlinux.org/netcfg.git/}} - Git repo for official package scripts.
+
{{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}}.}}
+
==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.
+
 
+
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]].
+
 
+
==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].)
+
 
+
Users wanting [[Bash]] completion support for netcfg, install the {{Pkg|bash-completion}} package from the official repositories.
+
 
+
==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.
+
 
+
=== Wireless Example ===
+
{{Warning|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}}
+
|}
+
 
+
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 for the 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:
+
KEY<nowiki>=</nowiki>'7b271c9a7c8a6ac07d12403a1f0792d7d92b5957ff8dfd56481ced43ec6a6515'
+
That should do it, without the need to reveal the passkey.<br />
+
}}
+
 
+
==Manual Operation==
+
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
+
 
+
== Automatic Operation ==
+
===Systemd Support (Recommended) ===
+
Since version 2.8.2 {{Pkg|netcfg}} provides systemd unit files.  Select from the following three features.
+
 
+
==== Net-Profiles ====
+
Edit {{ic|/etc/conf.d/netcfg}} eth0 refere to the file /etc/network.d/eth0 (copy from {{ic|/etc/network.d/examples/ethernet-static}})
+
# NETWORKS=(eth0)
+
 
+
Add service net-profiles (instead of networking) in {{ic|/etc/rc.conf}}
+
 
+
Other Solution:
+
 
+
Use the template service file {{ic|netcfg@xxx.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.
+
 
+
Example:
+
# systemctl enable netcfg@<profile-name>.service
+
 
+
==== Net-Auto-Wireless ====
+
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.
+
 
+
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}}.  Enable the {{ic|net-auto-wireless.service}} so systemd manages it.
+
 
+
{{Note|If  AUTO_PROFILES is not set, all wireless networks will be tried.}}
+
 
+
Example:
+
# systemctl enable net-auto-wireless.service
+
 
+
==== Net-Auto-Wired ====
+
This allows users to automatically connect to wired networks.  To use this feature, the {{Pkg|ifplugd}} is required.
+
 
+
Specify the desired wired interface with the {{ic|WIRED_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}} and enable the {{ic|net-auto-wired.service}} so systemd manages it.
+
 
+
Example:
+
# systemctl enable net-auto-wired.service
+
 
+
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).}}
+
 
+
=== SysV Support (Soon to be Depreciated/Legacy) ===
+
====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}}:
+
 
+
{{hc|/etc/rc.conf|<nowiki>
+
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>
+
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.
+
 
+
{{hc|/etc/conf.d/netcfg|<nowiki>
+
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}}:
+
 
+
{{hc|/etc/conf.d/netcfg|<nowiki>
+
NETWORKS=(menu)
+
</nowiki>}}
+
 
+
Additionally, the {{Pkg|dialog}} package is required.
+
 
+
{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}
+
 
+
====Net-Auto-Wireless====
+
To enable this feature, users must add {{ic|net-auto-wireless}} to the {{ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:
+
{{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}}:
+
 
+
{{hc|/etc/conf.d/netcfg|<nowiki>
+
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.
+
 
+
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.
+
 
+
====Net-Auto-Wired====
+
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}}:
+
 
+
{{hc|/etc/rc.conf|<nowiki>
+
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.
+
 
+
{{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).}}
+
 
+
==FAQ==
+
{{FAQ
+
|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.}}
+
 
+
{{FAQ
+
|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.}}
+
 
+
{{FAQ
+
|question=Do I still need ''(some thing)'' if I am using netcfg?
+
|answer=This question usually references {{ic|/etc/hosts}} and {{ic|/etc/hostname}}, which are both still required.}}
+

Latest revision as of 15:26, 16 July 2013

Redirect to: