Revision as of 20:08, 23 December 2013

NetworkManager is a program for providing detection and configuration for systems to automatically connect to network. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the GNOME project.

Graphical front-ends

To configure and have easy access to NetworkManager most people will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various applets exist for different types of desktops.

XFCE

network-manager-applet will work fine in XFCE, but in order to see notifications, including error messages, nm-applet needs an implementation of the Freedesktop desktop notifications specification (see the Galapago Project) to display them. To enable notifications install xfce4-notifyd, a package that provides an implementation for the specification.

Without such a notification daemon, nm-applet outputs the following errors to stdout/stderr:

If nm-applet is not prompting for a password when connecting to new wifi networks, and is just disconnecting immediately, you probably need to install gnome-keyring.

Openbox

To function properly in Openbox, the GNOME applet requires the xfce4-notifyd notification daemon for the same reason as in XFCE and the gnome-icon-theme package to be able to display the applet in the systray.

If you want to store authentication details (Wireless/DSL) install and configure gnome-keyring.

nm-applet installs the autostart file at /etc/xdg/autostart/nm-applet.desktop. If you have issues with it (e.g. nm-applet is started twice or is not started at all), see Openbox#Autostart directory or [1] for solution.

Other desktops and window managers

In all other scenarios it is recommended to use the GNOME applet. You will also need to be sure that the gnome-icon-theme package is installed to be able to display the applet.

Command line

Configuration

NetworkManager will require some additional steps to be able run properly.

Verify that your /etc/hosts is correct before continuing. If you previously tried to connect before doing this step, NetworkManager may have altered it. An example hostname line in /etc/hosts:

/etc/hosts

127.0.0.1 localhost
::1 localhost

In case you have nss-myhostname turned off, the line would look like:

/etc/hosts

127.0.0.1 my-laptop localhost
::1 my-laptop localhost

Note: It may be a good idea to use systemctl --type=service to ensure that no other service is running that may want to configure the network. Multiple networking services will conflict.

Enable NetworkManager

Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need nmcli or an applet to configure and connect.

You can enable NetworkManager at startup with the following command:

# systemctl enable NetworkManager

You can start the NetworkManager daemon immediately with the following command:

Enable NetworkManager Wait Online

If you have services which fail if they are started before the network is up, you have to use NetworkManager-wait-online.service in addition to the NetworkManager service. This is however hardly ever necessary since most network daemons start up fine, even if the network has not been configured yet.

You can enable NetworkManager Wait Online at startup with the following command:

# systemctl enable NetworkManager-wait-online

In some cases the service will still fail to start sucessfully on boot:

Set up PolicyKit permissions

With a working session, you have several options for granting the necessary privileges to NetworkManager:

Option 1. Run a PolicyKit authentication agent when you log in, such as /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1 (part of polkit-gnome). You will be prompted for your password whenever you add or remove a network connection.

Option 2. Add yourself to the wheel group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use sudo without entering the root password.

Option 3. Add yourself to the network group and create the following file:

All users in the network group will be able to add and remove networks without a password. This will not work under systemd if you do not have an active session with systemd-logind.

Network services with NetworkManager dispatcher

There are quite a few network services that you will not want running until NetworkManager brings up an interface. Good examples are NTPd and network filesystem mounts of various types (e.g. netfs). NetworkManager has the ability to start these services when you connect to a network and stop them when you disconnect. To activate the feature you need to start the NetworkManager-dispatcher.service.

Once the feature is active, scripts can be added to the /etc/NetworkManager/dispatcher.d directory. These scripts will need to have executable, user permissions. For security, it is good practice to make them owned by root:root and writable only by the owner.

The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. They receive two arguments: the name of the interface (e.g. eth0) and the status (up or down for interfaces and vpn-up or vpn-down for vpn connections). To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. 10_portmap or 30_netfs (which ensures that the portmapper is up before NFS mounts are attempted).

Warning:

For security reason. You should disable write access for group and other. For example use 755 mask. In other case it can refuse to execute script, with error message "nm-dispatcher.action: Script could not be executed: writable by group or other, or set-UID." in /var/log/messages.log.

If you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.

Avoiding the three seconds timeout

If the above is working, then this section is not relevant. However, there is a general problem related to running dispatcher scripts which take longer than 3 seconds to be executed. NetworkManager uses an internal timeout of 3 seconds (see the Bugtracker for more information) and automatically kills scripts that take longer than 3 seconds to finish. In this case, the dispatcher service file, located in /usr/lib/systemd/system/NetworkManager-dispatcher.service, has to be modified to remain active after exist. Create the service file /etc/systemd/system/NetworkManager-dispatcher.service with the following content:

Start OpenNTPD

The following example starts the OpenNTPD daemon when an interface is brought up. Save the file as /etc/NetworkManager/dispatcher.d/20_openntpd and make it executable.

awk '/State:/{print $2}'

Mount remote folder with sshfs

As the script is run in a very restrictive environment, you have to export SSH_AUTH_SOCK in order to connect to your SSH agent. There are different ways to accomplish this, see this link for more information. The example below works with gnome-keyring, and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely gnome-keyring has not yet started and the export will fail (hence the sleep). The UUID to match can be found with the command nmcli con status or nmcli con list.

Use dispatcher to connect to a VPN after a network-connection is established

In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network.

Remember to make it executable with chmod +x and to make the VPN connection available to all users.

Trying to connect using this setup will fail and NetworkManager will complain about 'no valid VPN secrets', because of the way VPN secrets are stored which brings us to step 2:

2. Edit your VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring that will be inaccessible for root: open up /etc/NetworkManager/system-connections/name of your VPN connection and change the password-flags and secret-flags from 1 to 0.

Alternatively put the password directly in the configuration file adding the section vpn-secrets:

[vpn]
....
password-flags=0
[vpn-secrets]
password=your_password

Note: It may now be necessary to re-open the NetworkManager connection editor and re-enter the VPN passwords/secrets.

Proxy settings

NetworkManager does not directly handle proxy settings, but if you are using GNOME, you could use proxydriver wich handles proxy settings using NetworkManager's informations. You can find the package for proxydriverAUR in the AUR.

In order for proxydriver to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (System -> Preferences -> Startup Applications):

Testing

NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to start the networkmanager daemon.

Some applets will provide you with a .desktop file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.

To start the GNOME applet in non-xdg-compliant window managers like Awesome:

nm-applet --sm-disable &

For static IPs you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.

Troubleshooting

Some fixes to common problems.

Using nm-applet, wifi networks don't prompt for password and just disconnect

This happens when no keyring package is installed. An easy solution is to install gnome-keyring.

No traffic via PPTP tunnel

PPTP connection logins successfully, you see ppp0 interface with correct VPN IP, but you cannot even ping remote IP. It is due to lack of MPPE (Microsoft Point-to-Point Encryption) support in stock Arch pppd. It is recommended to first try with the stock Arch ppp as it may work as intended.

To solve the problem it should be sufficient to install ppp-mppeAUR from the AUR.

WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require ppp-mppe rather than the stock ppp package. netctl seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See this blog post.

Network management disabled

Sometimes when NetworkManager shuts down but the pid (state) file does not get removed and you will get a 'Network management disabled' message. If this happens, you'll have to remove it manually:

# rm /var/lib/NetworkManager/NetworkManager.state

If this happens upon reboot, you can add an action to your /etc/rc.local to have it removed upon bootup:

Customizing resolv.conf

Hostname problems

Depending on the NetworkManager plugins used, the hostname can be forwarded to a router upon connection. The generic "keyfile" plugin does not forward the hostname in its default configuration. To make it forward the hostname, add the following to

/etc/NetworkManager/NetworkManager.conf

[keyfile]
hostname=your_hostname

The options under [keyfile] will be applied to network connections in the default /etc/NetworkManager/system-connections path.

Another option is to configure the DHCP client, which NetworkManager starts automatically, to forward it. To make dhclient forward the hostname requires to set a non-default option, dhcpcd forwards the hostname by default.

DHCP problems

NetworkManager uses dhclient as its default DHCP client, falling back to dhcpcd if the former is not installed.

To determine which DHCP client is used, journalctl can be used as below (dhclient in this example):

If you haven't already, installdhcpcd. Most clean installs will already have dhcpcd installed as it is part of the base package.

Now, tell NetworkManager that we're using dhcpcd:

/etc/NetworkManager/NetworkManager.conf

dhcp=dhcpcd

For some (incompliant) routers, you will not be able to connect properly unless you comment the line

require dhcp_server_identifier

in /etc/dhcpcd.conf (note that this file is distinct from dhcpd.conf). This should not cause issues unless you have multiple DHCP servers on your network (not typical); see this page for more information.

Missing default route

On at least one KDE4 system, no default route was created when establishing wireless connections with NetworkManager. Changing the route settings of the wireless connection to remove the default selection "Use only for resources on this connection" solved the issue.

3G modem not detected

Switching off WLAN on laptops

Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with rfkill. Install rfkill from the official repositories and use

$ watch -n1 rfkill list all

to check if the driver notifies rfkill about the wireless adapter's status.
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):

# rfkill event unblock X

Static IP settings revert to DHCP

Due to an unresolved bug, when changing default connections to static IP, nm-applet may not properly store the configuration change, and will revert to automatic DHCP.

To work around this issue you have to edit the default connection (e.g. "Auto eth0") in nm-applet, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP settings as desired, and click Apply. This will save a new connection with the given name.

Next, you will want to make the default connection not connect automatically. To do so, run nm-connection-editor (not as root). In the connection editor, edit the default connection (eg "Auto eth0") and uncheck "Connect automatically". Click Apply and close the connection editor.

Cannot edit connections as normal user

Forget hidden wireless network

Since hidden network are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:

# rm /etc/NetworkManager/system-connections/[SSID]

This works for any other connection.

VPN not working in Gnome

When setting up openconnect or vpnc connections in NetworkManager while using Gnome, you'll sometimes never see the dialog box pop up and the following error appears in /var/log/errors.log:

localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.

This is caused by the Gnome NM Applet expecting dialog scripts to be at /usr/lib/gnome-shell, when NetworkManager's packages put them in /usr/lib/networkmanager.
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):

Checking if networking is up inside a cron job or script

Some cron jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an if test for networking that queries NetworkManager's nm-tool and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network.

if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then
#Whatever you want to do if the network is online
else
#Whatever you want to do if the network is offline - note, this and the else above are optional
fi

This useful for a cron.hourly script that runs fpupdate for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from nm-tool; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.

Automatically unlock keyring after login

GNOME

Right click on the nm-applet icon in your panel and select Edit Connections and open the Wireless tab

Select the connection you want to work with and click the Edit button

Check the boxes “Connect Automatically” and “Available to all users”

Log out and log back in to complete.

Note: The following method is dated and known not to work on at least one machine!

In /etc/pam.d/gdm (or your corresponding daemon in /etc/pam.d), add these lines at the end of the "auth" and "session" blocks if they do not exist already:

SLiM login manager

KDE and OpenConnect VPN with password authentication

kdeplasma-applets-plasma-nm does not support to configure username and password for OpenConnect VPN connections in its GUI. You have to type both
values everytime you connect.
kdeplasma-applets-plasma-nm 0.9.3.2-1 and above is however capable of retrieving OpenConnect username and password directly from KWallet.

Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and
enter your credentials in key "VpnSecrets" in this form (replace THE_USERNAME and THE_PASSWORD with your actual values):

Next time you connect, username and password should appear in the "VPN secrets" dialog box.

Ignore specific devices

Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them.You can quickly and easily ignore devices by MAC by using the following in /etc/NetworkManager/NetworkManager.conf :

Connect faster

Disabling IPv6

Slow connection or reconnection to the network may be due to superfluous IPv6 queries in NetworkManager. If there is no IPv6 support on the local network, connecting to a network may take longer than normal while NetworkManager tries to establish an IPv6 connection that eventually times out. The solution is to disable IPv6 within NetworkManager which will make network connection faster. This has to be done once for every network you connect to.

Right-click on the network status icon.

Click on "Edit Connections".

Go to the "Wired" or "Wireless" tab, as appropriate.

Select the name of the network.

Click on "Edit".

Go to the "IPv6 Settings" tab.

In the "Method" dropdown, choose "Ignore/Disabled".

Click on "Save".

Speed up DHCP by disabling ARP probing in DHCPCD

dhcpcd contains an implementation of a recommendation of the DHCP standard (RFC2131 section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to /etc/dhcpcd.conf:

noarp

This is equivalent to passing --noarp to dhcpcd, and disables the described ARP probing, speeding up connections to networks with DHCP.

Use OpenDNS servers

Create /etc/resolv.conf.opendns with the nameservers:

nameserver 208.67.222.222
nameserver 208.67.220.220

or use Google DNS servers, because people have been getting ads via the OpenDNS servers lately

nameserver 8.8.8.8
nameserver 8.8.4.4

And have the dispatcher replace the discovered DHCP servers with the OpenDNS ones:

Enable DNS Caching

DNS requests can be sped up by caching previous requests locally for subsequent lookup. NetworkManager has a plugin to enable DNS caching using dnsmasq, but it is not enabled in the default configuration. It is, however, easy to enable using the following instructions.

Start by installingdnsmasq. Then, edit /etc/NetworkManager/NetworkManager.conf and add the following line under the [main] section:

dns=dnsmasq

Now restart NetworkManager or reboot. NetworkManager will automatically start dnsmasq and add 127.0.0.1 to /etc/resolv.conf. The actual DNS servers can be found in /var/run/NetworkManager/dnsmasq.conf. You can verify dnsmasq is being used by doing the same DNS lookup twice with dig and verifying the server and query times.