netctl

Related articles
Bridge with netctl
Network configuration
Wireless network configuration
netctl
is a CLI and profile-based network manager and an Arch project.
Installation
Install
the
netctl
package.
netctl's
#Special systemd units
used in automating connections require some additional dependencies; see that section for more information.
Other optional dependencies are shown in the table below.
Feature
Dependency
WPA
wpa_supplicant
DHCP
dhcpcd
or
dhclient
wifi-menu
dialog
PPPoE
ppp
Warning
Do not enable concurrent, conflicting network services. Use
systemctl --type=service
to ensure that no other network service is running before enabling a
netctl
profile/service.
Configuration
netctl
uses profiles to manage network connections and different modes of operation to start profiles automatically or manually on demand.
The
netctl
profile files are stored in
/etc/netctl/
and example configuration files are available in
/etc/netctl/examples/
.
To use an example profile, simply copy it from
/etc/netctl/examples/
to
/etc/netctl/
and configure it to your needs; see basic
#Example profiles
below. The first parameter you need to create a profile is the network
Interface
, see
Network configuration#Network interfaces
for details.
Tip
For wireless settings, you can use
wifi-menu
as root to generate the profile file in
/etc/netctl/
. The
dialog
package is required to use
wifi-menu
.
Use
SkipNoCarrier=yes
in your profile to enable a static IP profile on a wired interface no matter if the cable is connected or not.
See
netctl.profile(5)
for a complete list of profile options.
Usage
See
netctl(1)
for a complete list of
netctl
commands.
Starting a profile
Once you have created your profile, attempt to establish a connection, where
profile
is only the profile name, not the full path:
# netctl start
profile
If the above command results in a failure, then run
journalctl -xn
as root and
netctl status
profile
to obtain a more in-depth explanation of the failure.
Enabling a profile
A profile can be enabled to start at boot by using:
# netctl enable
profile
This will create and enable a
systemd
service that will start when the computer boots. Changes to the profile file will not propagate to the service file automatically. After such changes, it is necessary to reenable the profile:
# netctl reenable
profile
After enabling a profile, it will be started at next boot. Obviously this can only be successful, if the network cable for a wired connection is plugged in, or the wireless access point used in a profile is in range respectively.
If you need to switch multiple profiles frequently (i.e., traveling with a laptop), use
#Special systemd units
instead of enabling a profile.
Special systemd units
netctl
provides special
systemd
services for automatically switching of profiles for wired and wireless connections. See
netctl.special(7)
for a complete list of special systemd units.
Wired
Install
the
ifplugd
package and
start/enable
the
netctl-ifplugd@
interface
.service
systemd unit. DHCP profiles will be started/stopped when the network cable is plugged in/unplugged.
The
netctl-ifplugd@
interface
.service
will prefer profiles that use
DHCP
.
To automatically start a  static IP profile the option
ExcludeAuto=no
needs to be set in it.
To prioritize a profile with a static IP over DHCP profiles, you can set
Priority=2
, which is higher than the default priority given to DHCP profiles of
Priority=1
.
Wireless
Start/enable
netctl-auto@
interface
.service
systemd unit.
netctl
profiles will be started/stopped automatically as you move from the range of one network into the range of another network (roaming).
Profiles must use
Security=wpa-configsection
or
Security=wpa
to work with
netctl-auto
rather than
Security=wpa-config
.
If you want some wireless profile
not
to be started automatically by
netctl-auto@
interface
.service
, you have to explicitly add
ExcludeAuto=yes
to that profile.
You can use
priority=
in the
WPAConfigSection
(see
/etc/netctl/examples/wireless-wpa-configsection
) to set priority of a profile when multiple wireless access points are available. Larger numbers indicate a higher priority.
Note that
interface
is not literal, but to be substituted by the name of your device's interface, e.g.
netctl-auto@wlp4s0.service
. See
netctl.profile(5)
for details.
Note
If any of the profiles contain errors, such as an empty or misquoted
Key=
variable, the unit will fail to load with the message
"Failed to read or parse configuration '/run/network/wpa_supplicant_wlan0.conf'
, even when that profile is not being used.
If you have previously
enabled a profile
through
netctl
, run
netctl disable
profile
to prevent the profile from starting twice at boot.
It is possible to manually control an interface otherwise managed by
netctl-auto
without having to stop
netctl-auto.service
. This is done using the
netctl-auto
command. For a complete list of available actions see
netctl-auto(1)
.
Tips and tricks
Example profiles
Wired
For a DHCP connection, only the
Interface
has to be configured after copying the
/etc/netctl/examples/ethernet-dhcp
example profile to
/etc/netctl
.
For example:
/etc/netctl/
my_dhcp_profile
Interface=enp1s0
Connection=ethernet
IP=dhcp
For a static IP configuration copy the
/etc/netctl/examples/ethernet-static
example profile to
/etc/netctl
and modify
Interface
,
Address
,
Gateway
and
DNS
) as needed.
For example:
/etc/netctl/
my_static_profile
Interface=enp1s0
Connection=ethernet
IP=static
Address=('10.1.10.2/24')
Gateway='10.1.10.1'
DNS=('10.1.10.1')
Take care to include the subnet notation of
/24
. It equates to a netmask of
255.255.255.0
) and without it the profile will fail to start. See also
CIDR notation
. To alias more than one IP address per a NIC set
Address=('10.1.10.2/24' '192.168.1.2/24')
. To alias more than one DNS server address set Eg.
DNS=('1.1.1.1' '1.0.0.1')
.
Wireless (WPA-PSK)
The following applies for the standard wireless connections using a pre-shared key (WPA-PSK).
/etc/netctl/wireless-wpa
Description='A simple WPA encrypted wireless connection using 256-bit PSK'
Interface=wlp2s2
Connection=wireless
Security=wpa
IP=dhcp
ESSID=
your_essid
Key=\"64cf3ced850ecef39197bb7b7b301fc39437a6aa6c6a599d0534b16af578e04a
Note
Make sure to use the
special quoting rules
for the
Key
variable as explained in
netctl.profile(5) § SPECIAL QUOTING RULES
.
If the passphrase fails, try removing the
\"
in the
Key
variable.
Although "encrypted", the key that you put in the profile configuration is enough to connect to a WPA-PSK network. Therefore this process is only useful for hiding the human-readable version of the passphrase. This will not prevent anyone with read access to this file from connecting to the network.
Obfuscate wireless passphrase
You can also follow the following step to obfuscate the wireless passphrase (
wifi-menu
does it automatically when using the
-o
flag):
Users
not
wishing to have the passphrase to their wireless network stored in
plain text
have the option of storing the corresponding 256-bit pre-shared key instead, which is calculated from the passphrase and the SSID using standard algorithms.
Calculate your 256-bit PSK using
wpa_passphrase
:
$ wpa_passphrase
your_essid
network={
  ssid="
your_essid
"
  #psk="
passphrase
"
  psk=64cf3ced850ecef39197bb7b7b301fc39437a6aa6c6a599d0534b16af578e04a
}
The
pre-shared key
(psk) now needs to replace the plain text passphrase of the
Key
variable in the profile.
Using an experimental GUI
If you want a graphical user interface to manage
netctl
and your connections and you are not afraid of highly experimental unofficial packages, there are some options available.
netctl-gui
AUR
provides a Qt-based graphical interface, DBus daemon and KDE widget.
netmenu
AUR
uses
dmenu
as its graphical interface.
There is also an application that displays desktop notifications on profile changes and shows a tray icon:
netctl-tray
AUR
.
Bonding
From
kernel documentation
:
The Linux bonding driver provides a method for aggregating multiple network interfaces into a single logical "bonded" interface. The behavior of the bonded interfaces depends on the mode. Generally speaking, modes provide either hot standby or load balancing services. Additionally, link integrity monitoring may be performed.
Load balancing
Copy
/etc/netctl/examples/bonding
to
/etc/netctl/bond0
and edit it, for example:
/etc/netctl/bond0
Description='Bond Interface'
Interface='bond0'
Connection=bond
BindsToInterfaces=('eth0' 'eth1')
IP=dhcp
IP6=stateless
Now you can disable your old configuration and set
bond0
to be started automatically. Switch to the new profile, for example:
# netctl switch-to bond0
Note
This uses the round-robin policy, which is the default for the
bonding
driver. See
official documentation
for details.
Setting the MODE in the netctl configuration is not always successful and it may be necessary to pass options directly to the bonding module on load as noted
here
.  This may be needed to use LACP / mode 4.
Tip
To check the status and bonding mode:
$ cat /proc/net/bonding/bond0
Wired to wireless failover
This example describes how to use
bonding
to fallback to wireless when the wired Ethernet goes down. This is most useful when both the wired and wireless interface will be connected to the same network. Your wireless router/access point must be configured in
bridge
mode.
You will need an additional package:
wpa_supplicant
.
First,
load the module at boot
:
/etc/modules-load.d/bonding.conf
bonding
Then, configure the options of the
bonding
driver to use
active-backup
and configure the
primary
parameter to the device you want to be the active one (normally the wired interface). Also, be sure to use the same device name as returned when running
ip link
:
/etc/modprobe.d/bonding.conf
options bonding mode=active-backup miimon=100 primary=eth0 max_bonds=0
The
miimon
option is needed, for the link failure detection. The
max_bonds
option avoids the
Interface bond0 already exists
error. More information can be obtained on the
kernel documentation
.
Next, configure a netctl profile to enslave the two hardware interfaces. Use the name of all the devices you want to enslave. If you have more than two wired or wireless interfaces, you can enslave all of them on a bond interface. But, for most cases you will have only two devices, a wired and a wireless one:
/etc/netctl/failover
Description='A wired connection with failover to wireless'
Interface='bond0'
Connection=bond
BindsToInterfaces=('eth0' 'wlan0')
IP='dhcp'
Disable any other profiles (specially a wired or wireless) you had enabled before and then enable the failover profile on startup:
# netctl enable failover
Now you need to configure
wpa_supplicant
to connect to any known network you wish. You should create a file for each interface and enable it on systemd. Create the following file with this content:
/etc/wpa_supplicant/wpa_supplicant-wlan0.conf
ctrl_interface=/run/wpa_supplicant
update_config=1
And append to the end of this file any network you want to connect to:
network={
    ssid="SSID"
    psk=PSK
}
To generate the obfuscated PSK you can run
wpa_passphrase
as on the
wpa_supplicant#Connecting with wpa_passphrase
page.
Now,
enable
the
wpa_supplicant@
template service on the network interface, for example
wpa_supplicant@wlan0
.
You can try now to reboot your machine and see if your configuration worked.
Now, you can test your failover setup, by initiating a big download. Unplug your wired interface. Your download should keep going over the wireless interface. Then, plug your wired interface again and it should keep working. You can debug by checking
journalctl
for the
netctl@failover.service
and
wpa_supplicant@wlan0.service
units.
Using any interface
In some cases it may be desirable to allow a profile to use any interface on the system. A common example use case is using a common disk image across many machines with differing hardware (this is especially useful if they are headless). If you use the kernel's naming scheme, and your machine has only one ethernet interface, you can probably guess that eth0 is the right interface. If you use udev's
Predictable Network Interface Names
, however, names will be assigned based on the specific hardware itself (e.g. enp1s0), rather than simply the order that the hardware was detected (e.g. eth0, eth1). This means that a netctl profile may work on one machine and not another, because they each have different interface names.
A quick and dirty solution is to make use of the
/etc/netctl/interfaces/
directory. Choose a name for your interface alias (
en-any
in this example), and write the following to a file with that name (making sure it is
executable
).
/etc/netctl/interfaces/en-any
#!/bin/sh
for interface in /sys/class/net/en*; do
        break;
done
Interface=$(basename "$interface")
echo "en-any: using interface $Interface";
Then create a profile that uses the interface. Pay special attention to the
Interface
directive. The rest are only provided as examples.
/etc/netctl/wired
Description='Wired'
Interface=en-any
Connection=ethernet
IP=static
Address=('192.168.1.15/24')
Gateway='192.168.1.1'
DNS=('192.168.1.1')
When the
wired
profile is started, any machine using the two files above will automatically bring up and configure the first ethernet interface found on the system, regardless of what name udev assigned to it. Note that this is not the most robust way to go about configuring interfaces. If you use multiple interfaces, netctl may try to assign the same interface to them, and will likely cause a disruption in connectivity. If you do not mind a more complicated solution,
netctl-auto
is likely to be more reliable.
Using hooks
netctl supports hooks in
/etc/netctl/hooks/
and per interface hooks in
/etc/netctl/interfaces/
. You can set any option in a hook/interface that you can
in a profile. Most importantly this includes
ExecUpPost
and
ExecDownPre
.
When a profile is read, netctl sources
all executable
scripts in
hooks
, then it reads the profile file for the connection and finally it sources an executable script with the name of the interface used in the profile from the
interfaces
directory. Therefore, declarations in an interface script override declarations in the profile, which override declarations in hooks.
The variables
$INTERFACE
and
$ACTION
are available in hooks/interfaces
only
when using
netctl-auto
Examples
Execute commands on established connection
/etc/netctl/hooks/myservices
#!/bin/sh
ExecUpPost="systemctl start crashplan.service; systemctl start dropbox@<username>.service"
ExecDownPre="systemctl stop crashplan.service; systemctl stop dropbox@<username>.service"
Set default DHCP client
To set or change the DHCP client used for all profiles:
/etc/netctl/hooks/dhcp
#!/bin/sh
DHCPClient='dhclient'
Do not forget to make the file
executable
.
Alternatively, it may also be specified for a specific network interface by creating an executable file
/etc/netctl/interfaces/<interface>
with the following line:
DHCPClient='dhclient'
This article or section needs expansion.
Reason:
It would be useful to replace the example with a general hook that executes different actions depending on
$ACTION
being CONNECT and DISCONNECT. (Discuss in
Talk:Netctl
)
Minimal WPAConfigSection
As stated in
netctl.profile(5) § OPTIONS FOR ‘WIRELESS’ CONNECTIONS
, the
WPAConfigSection
variable is an array of configuration lines passed to
wpa_supplicant
. So, a minimal WPAConfigSection would contain:
Description='A wireless connection using a custom network block configuration'
Interface=wlan0
Connection=wireless
Security=wpa-configsection
IP=dhcp
WPAConfigSection=(
    'ssid="University"'
    'psk="very secret passphrase"'
)
Note
If trying to connect to an SSID with non-ASCII characters (unicode, emoji, etc), you can specify the SSID as hex instead of as a string, e.g.
ssid=F09F90BA
for "🐺". When unsure on the hex encoding, run
wifi-menu
(be sure to remove the \ and x characters).
/etc/resolv.conf
If you use
DNS*
options in your profile,
netctl
calls
resolvconf
to overwrite
resolv.conf
.
Troubleshooting
Job for netctl@wlan(...).service failed
Warning
This section assumes that there is no other network service running before starting a
netctl
profile/service. See
#Installation
for details.
Some people have an issue when they connect to a network with
netctl
, for example:
# netctl start wlan0-ssid
Job for netctl@wlan0\x2ssid.service failed. See 'systemctl status netctl@wlan0\x2ssid.service' and 'journalctl -xn' for details.
When looking at the journal from running
journalctl -xn
as root, either of the following are shown:
1. If your device (
wlan0
in this case) is up:
network[2322]: The interface of network profile 'wlan0-ssid' is already up
Setting the interface down should resolve the problem:
# ip link set wlan0 down
Then retry:
# netctl start wlan0-ssid
2. If the error continues, try again after adding the
ForceConnect
option:
/etc/netctl/wlan0-ssid
...
ForceConnect=yes
Save it and try to connect with the profile:
# netctl start wlan0-ssid
dhcpcd: ipv4_addroute: File exists
On some systems dhcpcd in combination with netctl causes timeout issues on resume, particularly when having switched networks in the meantime. netctl will report that you are successfully connected but you still receive timeout issues. In this case, the old default route still exists and is not being renewed. A workaround to avoid this misbehaviour is to switch to
dhclient
as the default dhcp client. More information on the issue can be found
here
.
DHCP timeout issues
If you are having timeout issues when requesting leases via DHCP you can set the timeout value higher than netctl's 30 seconds by default. Create a file in
/etc/netctl/hooks/
or
/etc/netctl/interfaces/
, add
TimeoutDHCP=40
to it for a timeout of 40 seconds and make the file executable.
dhcpcd debugging
If dhcpcd fails to obtain an address, add the
-d
option to
/usr/lib/netctl/dhcp
and then run
journalctl -xe
as root to view the debugging messages which may indicate, for example, that the IP address offered by the server is rejected by the client after detecting that the IP address is already in use.
Connection timeout issues
If you are having timeout issues that are unrelated to DHCP (on a static ethernet connection for example), and are experiencing errors similar to the following when starting your profile:
# journalctl _SYSTEMD_UNIT=netctl@
profile
.service
Starting network profile '
profile
'...
No connection found on interface 'eth0' (timeout)
Failed to bring the network up for profile '
profile'
Then you should increase carrier and up timeouts by adding
TimeoutUp=
and
TimeoutCarrier=
to your profile file:
/etc/netctl/
profile
...
TimeoutUp=300
TimeoutCarrier=300
Do not forget to reenable your profile:
# netctl reenable
profile
Problems with netctl-auto on resume
Sometimes
netctl-auto
fails to reconnect when the system resumes from suspend, hibernate or hybrid-sleep. An easy solution is to restart the service for
netctl-auto
. 
This can be automated with an additional service like the following:
/etc/systemd/system/netctl-auto-resume@.service
[Unit]
Description=restart netctl-auto on resume.
Requisite=netctl-auto@%i.service
After=sleep.target

[Service]
Type=oneshot
ExecStart=/usr/bin/systemctl restart netctl-auto@%i.service

[Install]
WantedBy=sleep.target
To
enable
this service for your wireless card, for example, enable
netctl-auto-resume@wlan0.service
as root. Change
wlan0
to the required network interface.
If the device is not yet running on resume when the unit is started, this will fail. It can be fixed by adding the following dependency in the
After
line:
/etc/systemd/system/netctl-auto-resume@.service
...
After=sleep.target sys-subsystem-net-devices-%i.device
...
netctl-auto does not automatically unblock a wireless card to use an interface
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by the kernel. This can be handled by
rfkill
.
If you want
netctl-auto
to automatically unblock your wireless card to connect to a particular network, set
RFKill=++auto++
option for the wireless connection of your choice, as specified in the
netctl.profile(5)
.
RTNETLINK answers: File exists (with multiple NICs)
This is a very misleading response, it really means that you have assigned a default gateway in an earlier netctl control file. When netctl starts up the n-th NIC and goes to set its local route, it fails because there is already a default route from n-1.
Remove it and everything works, except you no longer have a default route and so cannot access things such as the internet.
ExecUpPost
does not work as it gets executed for each network card.
A possible solution is creating a new service.  Replace "FIRST_INTERFACE" and "SECOND_INTERFACE" with your interface names, and replace "192.168.xxx.yyy" with your default gateway.
/etc/systemd/system/defaultrouter.service
[Unit]
Description="Configure default gateway"
Requires=netctl@FIRST_INTERFACE.service netctl@SECOND_INTERFACE.service
After=netctl@FIRST_INTERFACE.service netctl@SECOND_INTERFACE.service

[Service]
Type=oneshot
ExecStart=/usr/bin/ip route add default via 192.168.xxx.yyy

[Install]
WantedBy=network-online.target
Problems with Eduroam and other MSCHAPv2 connections
See
wpa_supplicant#Problems with Eduroam
.
Journal warnings for profiles using .include directives
Profiles still using systemd's old
.include
directives will produce journal warnings, for example:
systemd[1]: /etc/systemd/system/netctl@<profile>.service:1: .include directives are deprecated, and support for them will be removed in a future version of systemd. Please use drop-in files instead.
See
FS#59494
for details.
Executing
netctl reenable
profile
will update the profile to the new
drop-in unit file
format.
Hooks do not work
If you have multiple hooks in
/etc/netctl/hooks/
, variables like
ExecUpPost
and
ExecDownPre
will be executed only from one file. To fix this, define the variables like this:
/etc/netctl/hooks/test
ExecUpPost="some command ; "$ExecUpPost
ExecDownPre="some command ; "$ExecDownPre
This will append your commands to be executed with already defined ones.
Network mounts time out on shutdown
If you are using network mounts in combination with
netctl-ifplugd
or
netctl-auto
, it may be necessary to unmount them before the corresponding services are stopped. One way to achieve this is to create an
drop-in file
for
netctl-ifplugd@.service
or
netctl-auto@.service
with the following content:
/etc/systemd/system/netctl-*@.service.d/unmount_on_shutdown.conf
[Unit]
Wants=remote-fs-pre.target
Before=remote-fs-pre.target
This will make sure the network mounts are disconnected before the automatic network service is stopped.
See also
Initial mailing list announcement
Official announcement thread
Official news announcement