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, [[Wikipedia:PPP|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]].

−

{{Note|1={{Pkg|netcfg}}>=2.8.9 drops deprecated {{ic|/etc/[[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==

+

+

== 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 passphrase 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]].

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.

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).

+

+

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.

−

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

+

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!}}

{{Warning|Be wary of examples found on the internet as they often contain deprecated options that may cause problems!}}

{| class="wikitable" align="center"

{| class="wikitable" align="center"

−

! Connection !! Type !! Example Profile

+

! Connection !! Type !! Example Profile !! Information

|-

|-

| rowspan="3"| '''Wired'''

| rowspan="3"| '''Wired'''

−

| Dynamic IP || {{ic|ethernet-dhcp}}

+

| Dynamic IP || {{ic|ethernet-dhcp}} ||

|-

|-

−

| Static IP || {{ic|ethernet-static}}

+

| Static IP || {{ic|ethernet-static}} ||

|-

|-

−

| Routed || {{ic|ethernet-iproute}}

+

| Routed || {{ic|ethernet-iproute}} || Can be checked with {{ic|route}} from the {{Pkg|net-tools}} package.

| {{ic|wireless-wpa-configsection}}<br><font size=1>(the {{Pkg|wpa_supplicant}} configuration is stored as a string)</font>

+

| {{ic|wireless-wpa-configsection}} || The {{Pkg|wpa_supplicant}} configuration is stored as a string.

|}

|}

Line 65:

Line 68:

** Note that WEP ''string'' keys (not ''hex'' keys) must be specified with a leading {{ic|s:}} (e.g. {{ic|1=KEY="s:''somepasskey''"}}).

** 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|If you are using netcfg inside a VPS, please see [[Virtual_Private_Server#Moving_your_VPS_from_network_configuration_in_rc.conf_to_netcfg_.28tested_with_OpenVZ.29|the appropriate page]].}}

+

+

{{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.}}

Line 71:

Line 76:

{{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.}}

{{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.}}

−

==Manual Operation==

+

{{

+

Note|1=By default netcfg uses dhcpcd for configuring network interfaces. An alternate to dhcpcd is dhclient. To use dhclient, set DHCLIENT='yes' in appropriate profile configuration.

+

}}

+

+

== Manual Operation ==

+

To connect a profile:

To connect a profile:

+

# netcfg mynetwork

# netcfg mynetwork

To disconnect a profile:

To disconnect a profile:

+

# netcfg down mynetwork

# netcfg down mynetwork

−

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.

+

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 ==

+

+

=== Just one profile ===

+

+

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

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

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=(last)

+

NETWORKS=(last)}}

−

</nowiki>}}

+

+

{{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.}}

−

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}}:

+

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}}:

−

{{hc|/etc/conf.d/netcfg|<nowiki>

+

{{hc|/etc/conf.d/netcfg|2=

−

NETWORKS=(menu)

+

NETWORKS=(menu)}}

−

</nowiki>}}

Additionally, the {{Pkg|dialog}} package is required.

Additionally, the {{Pkg|dialog}} package is required.

+

+

{{Note|The {{ic|1=NETWORKS=(menu)}} setting cannot be used anymore when switching to systemd. See {{bug|31377}} for details.}}

{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}

{{Tip|Access the menu at any time by running {{ic|netcfg-menu}} in a terminal.}}

=== Net-Auto-Wireless ===

=== 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.

+

+

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}} or {{ic|wireless-wpa}} 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}}.

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}}.

Line 120:

Line 141:

{{Note|If AUTO_PROFILES is not set, all wireless networks will be tried.}}

{{Note|If AUTO_PROFILES is not set, all wireless networks will be tried.}}

−

Enable the {{ic|net-auto-wireless.service}} so systemd manages it.

+

Enable {{ic|net-auto-wireless.service}} so systemd manages it.

−

# systemctl enable net-auto-wireless.service

+

+

# systemctl enable net-auto-wireless

=== Net-Auto-Wired ===

=== Net-Auto-Wired ===

−

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

+

+

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

Specify the desired wired interface with the {{ic|WIRED_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}}.

Specify the desired wired interface with the {{ic|WIRED_INTERFACE}} variable in {{ic|/etc/conf.d/netcfg}}.

−

Enable the {{ic|net-auto-wired.service}} so systemd manages it.

+

Enable {{ic|net-auto-wired.service}} so systemd manages it.

−

# systemctl enable net-auto-wired.service

+

# systemctl enable 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|1=CONNECTION = "ethernet"}} or {{ic|"ethernet-iproute"}} and {{ic|1=INTERFACE = WIRED_INTERFACE}} until one of them succeeds.

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.

|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. Alternatively, you could be creative with the use of netcfg's {{ic|POST_UP}} functionality to handle some use cases.}}

+

|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 {{ic|/etc/hostname}}, which are both still required.}}

|answer=This question usually references {{ic|/etc/hosts}} and {{ic|/etc/hostname}}, which are both still required.}}

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.

Contents

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.

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!

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.

Note: By default netcfg uses dhcpcd for configuring network interfaces. An alternate to dhcpcd is dhclient. To use dhclient, set DHCLIENT='yes' in appropriate profile configuration.

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:

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 or wireless-wpa 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.