NetworkManager - ArchWiki

Jump to content

# NetworkManager

From ArchWiki

Related articles

- Network configuration
- Wireless network configuration

NetworkManager is a program for providing detection and configuration for systems to automatically connect to networks. 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.

This article or section needs expansion.

Reason: Clear text storage of secrets is not limited to just Wi-Fi passwords. The secrets are stored in files (and folder) only accesible to root. (Discuss in Talk:NetworkManager)
Warning: By default, Wi-Fi passwords are stored in clear text, see #Encrypted Wi-Fi passwords.

## Installation

NetworkManager can be installed with the package networkmanager, which contains a daemon, a command line interface (`nmcli`) and a curses‐based interface (`nmtui`).

### Enable NetworkManager

After installation, you should start/enable `NetworkManager.service`. 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.

Note: If systemd-resolved is not started, an error message will start flooding your logs. See #Unit dbus-org.freedesktop.resolve1.service not found for more info.

### Additional interfaces

- nm-connection-editor for a graphical user interface,
- network-manager-applet for a system tray applet (`nm-applet`).

Note: You must ensure that no other service that wants to configure the network is running; in fact, multiple networking services will conflict. You can find a list of the currently running services with `systemctl --type=service` and then stop them. See #Configuration to enable the NetworkManager service.

### Mobile broadband support

NetworkManager uses ModemManager for mobile broadband connection support.

Install modemmanager and usb_modeswitch. Afterwards enable and start `ModemManager.service`.

It may be necessary to restart `NetworkManager.service` for it to detect ModemManager. After you restart it, re-plug the modem again and it should be recognized.

Add connections from a front-end (e.g. nm-connection-editor) and select mobile broadband as the connection type. After selecting your ISP and billing plan, APN and other settings should be filled in automatically using information from mobile-broadband-provider-info.

### PPPoE / DSL support

Install rp-pppoe package for PPPoE / DSL connection support. To actually add PPPoE connection, use `nm-connection-editor` and add new DSL/PPPoE connection.

### VPN support

NetworkManager since version 1.16 has native support for WireGuard, all it needs is the `wireguard` kernel module. Read the WireGuard in NetworkManager blog post for details.

Support for other VPN types is based on a plug-in system. They are provided in the following packages:

- networkmanager-openconnect for OpenConnect
- networkmanager-openvpn for OpenVPN
- networkmanager-pptp for PPTP Client
- networkmanager-vpnc for Vpnc
- networkmanager-strongswan for strongSwan
- networkmanager-fortisslvpn-gitAUR
- networkmanager-iodine-gitAUR
- networkmanager-libreswanAUR
- networkmanager-l2tp
- networkmanager-ssh-gitAUR
- network-manager-sstp

Warning: There are a lot of bugs related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.
Note: To have fully functioning DNS resolution when using VPN, you should set up conditional forwarding.

## Usage

NetworkManager comes with nmcli(1) and nmtui(1).

### nmcli examples

List nearby Wi-Fi networks:

    $ nmcli device wifi list

Connect to a Wi-Fi network:

    $ nmcli device wifi connect SSID_or_BSSID password password

Connect to a hidden Wi-Fi network:

    $ nmcli device wifi connect SSID_or_BSSID password password hidden yes

Connect to a Wi-Fi on the `wlan1` interface:

    $ nmcli device wifi connect SSID_or_BSSID password password ifname wlan1 profile_name

Disconnect an interface:

    $ nmcli device disconnect ifname eth0

Get a list of connections with their names, UUIDs, types and backing devices:

    $ nmcli connection show

Activate a connection (i.e. connect to a network with an existing profile):

    $ nmcli connection up name_or_uuid

Delete a connection:

    $ nmcli connection delete name_or_uuid

See a list of network devices and their state:

    $ nmcli device

Turn off Wi-Fi:

    $ nmcli radio wifi off

### Edit a connection

For a comprehensive list of settings, see nm-settings(5).

Firstly you need to get list of connections:

    $ nmcli connection

    NAME                UUID                                  TYPE      DEVICE
    Wired connection 2  e7054040-a421-3bef-965d-bb7d60b7cecf  ethernet  enp5s0
    Wired connection 1  997f2782-f0fc-301d-bfba-15421a2735d8  ethernet  enp0s25
    MY-HOME-WIFI-5G     92a0f7b3-2eba-49ab-a899-24d83978f308  wifi       --

Here you can use the first column as connection-id used later. In this example we pick `Wired connection 2` as a connection-id.

You have three methods to configure a connection `Wired connection 2` after it has been created:

nmcli interactive editor
  `nmcli connection edit 'Wired connection 2'`.
  Usage is well documented from the editor.

nmcli command line interface
  `nmcli connection modify 'Wired connection 2' setting.property value`. See nmcli(1) for usage. For example you can change its IPv4 route metric to 200 using `nmcli connection modify 'Wired connection 2' ipv4.route-metric 200` command.

To remove a setting pass an empty field ("") to it like this:

  `nmcli connection modify 'Wired connection 2' setting.property ""`

Connection file
  In `/etc/NetworkManager/system-connections/`, modify the corresponding `Wired connection 2.nmconnection` file .
  Do not forget to reload the configuration file with `nmcli connection reload`.

## Front-ends

To configure and have easy access to NetworkManager, most users 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 desktop environments have their own applet. Otherwise you can use #nm-applet.

### GNOME

GNOME has a built-in tool, accessible from the Network settings.

### KDE Plasma

Install the plasma-nm package. After that, add it to the KDE taskbar via the Panel options > Add widgets > Networks menu.

### nm-applet

network-manager-applet is a GTK 3 front-end which works under Xorg environments with a systray.

To store connection secrets install and configure GNOME/Keyring.

Be aware that after enabling the tick-box option `Make available to other users` for a connection, NetworkManager stores the password in plain-text, though the respective file is accessible only to root (or other users via `nm-applet`). See #Encrypted Wi-Fi passwords.

In order to run `nm-applet` without a systray, you can use trayer or stalonetray. For example, you can add a script like this one in your path:

    nmgui

    #!/bin/sh
    nm-applet    2>&1 > /dev/null &
    stalonetray  2>&1 > /dev/null
    killall nm-applet

When you close the stalonetray window, it closes `nm-applet` too, so no extra memory is used once you are done with network settings.

The applet can show notifications for events such as connecting to or disconnecting from a WiFi network. For these notifications to display, ensure that you have a notification server installed - see Desktop notifications. If you use the applet without a notification server, you might see some messages in stdout/stderr, and the app might hang. See [1].

In order to run `nm-applet` with such notifications disabled, start the applet with the following command:

    $ nm-applet --no-agent

Tip: `nm-applet` might be started automatically with a autostart desktop file, to add the --no-agent option modify the Exec line there, i.e.

    Exec=nm-applet --no-agent

Warning: On i3, if nm-applet is started with the `--no-agent` option, it is not possible to connect to a new encrypted WiFi network by clicking on the item list because no password input dialogue window will pop out. journal will show `no secrets: No agents were available for this request`.

#### Appindicator

As of version 1.18.0 Appindicator support is available in the official network-manager-applet package. To use nm-applet in an Appindicator environment start the applet with the following command:

    $ nm-applet --indicator

### networkmanager-dmenu

Alternatively there is networkmanager-dmenu-gitAUR which is a small script to manage NetworkManager connections with dmenu or rofi instead of `nm-applet`. It provides all essential features such as connection to existing NetworkManager wifi or wired connections, connect to new wifi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch nm-connection-editor GUI, connect to Bluetooth networks.

## Configuration

NetworkManager will require some additional steps to be able run properly. Make sure you have configured `/etc/hosts` as described in Network configuration#Set the hostname section.

NetworkManager has a global configuration file at `/etc/NetworkManager/NetworkManager.conf`. Additional configuration files can be placed in `/etc/NetworkManager/conf.d/`. Usually no configuration needs to be done to the global defaults.

After editing a configuration file, the changes can be applied by running:

    # nmcli general reload

### NetworkManager-wait-online

Enabling `NetworkManager.service` also enables `NetworkManager-wait-online.service`, which is a oneshot system service that waits for the network to be configured. The latter has `WantedBy=network-online.target`, so it will finish only when `network-online.target` itself is enabled or pulled in by some other unit. See also systemd#Running services after the network is up.

By default, `NetworkManager-wait-online.service` waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see nm-online(1)). If `NetworkManager-wait-online.service` finishes before the network is really up, resulting in failed services on boot, extend the unit to remove the `-s` from the `ExecStart` line:

    [Service]
    ExecStart=
    ExecStart=/usr/bin/nm-online -q

Be aware that this can cause other issues.

In some cases, the service will still fail to start successfully on boot due to the timeout setting being too short. Edit the service to change `NM_ONLINE_TIMEOUT` from `60` to a higher value.

### Set up PolicyKit permissions

See General troubleshooting#Session permissions for setting up a working session.

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

- Option 1. Run a Polkit 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:

    /etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules

    polkit.addRule(function(action, subject) {
      if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {
        return polkit.Result.YES;
      }
    });

  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.

### Proxy settings

NetworkManager does not directly handle proxy settings, but if you are using GNOME or KDE, you could use proxydriver which handles proxy settings using NetworkManager's information. proxydriver is found in the package proxydriverAUR.

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 (see GNOME#Autostart).

    xhost +si:localuser:username

See also Proxy settings.

### Checking connectivity

NetworkManager can try to reach a webserver after connecting to a network in order to determine if it is e.g behind a captive portal. The default host (configured in `/usr/lib/NetworkManager/conf.d/20-connectivity.conf`) is ping.archlinux.org. To use a different webserver or to disable connectivity checking, create `/etc/NetworkManager/conf.d/20-connectivity.conf`, see NetworkManager.conf(5) § CONNECTIVITY SECTION. Below is an example of using GNOME servers (it does not require the use of GNOME):

    /etc/NetworkManager/conf.d/20-connectivity.conf

    [connectivity]
    uri=http://nmcheck.gnome.org/check_network_status.txt

To disable NetworkManager's connectivity check, use the following configuration. This can be useful when connected to a VPN that blocks connectivity checks.

The factual accuracy of this article or section is disputed.

Reason: According to NetworkManager.conf(5) § CONNECTIVITY SECTION, the option is `enabled=false` not `.set.enabled=false`. (Discuss in Talk:NetworkManager)

    /etc/NetworkManager/conf.d/20-connectivity.conf

    [connectivity]
    .set.enabled=false

Note: Although automatic connectivity checks are a potential privacy leak, Arch Linux's default connectivity URL is committed to not logging any access. See [2] [3].

### Captive portals

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Complex scripts should not be maintained on the wiki. (Discuss in Talk:NetworkManager)

For those behind a captive portal, the desktop manager may automatically open a window asking for credentials. If your desktop does not, you can use capnet-assist package (however, it currently it has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:

    /etc/NetworkManager/dispatcher.d/90-open_captive_portal

    #!/bin/sh -e
    # Script to dispatch NetworkManager events
    #
    # Runs shows a login webpage on walled garden networks.
    # See NetworkManager(8) for further documentation of the dispatcher events.

    PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

    if [ -x "/usr/bin/logger" ]; then
        logger="/usr/bin/logger -s -t captive-portal"
    else
        logger=":"
    fi

    wait_for_process() {
        PNAME=$1
        while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do
            sleep 3;
        done
    }

    #launch the browser, but on boot we need to wait that nm-applet starts
    start_browser() {
        local user="$1"
        local display="$2"

        export DISPLAY="$display"
        wait_for_process nm-applet

        export XAUTHORITY="/home/$user/.Xauthority"

        $logger "Running browser as '$user' with display '$display' to login in captive portal"
        sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null
    }

    # Run the right scripts
    case "$2" in
        connectivity-change)
        $logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"
        if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then
            # Match last column of who's output with ' :[at least one digit] '
            who | awk '$NF ~ /\(:[0-9]+\)/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \
            while read user display; do
                start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"
            done
        fi
        ;;
        *)
        # In a down phase
        exit 0
        ;;
    esac

You will need to restart `NetworkManager.service` or reboot for this to start working. Once you do, the dispatcher script should open a login window once it detects you are behind a captive portal.

Another solution is captive-browser-gitAUR based on Google Chrome.

### DHCP client

By default NetworkManager uses its internal DHCP client. The internal DHCPv4 plugin is based on the nettools' n-dhcp4 library, while the internal DHCPv6 plugin is made from code based on systemd-networkd.

To use a different DHCP client install one of the alternatives:

- dhclient - dhclient.
- dhcpcd - dhcpcd.

To change the DHCP client backend, set the option `main.dhcp=dhcp_client_name` with a configuration file in `/etc/NetworkManager/conf.d/`. E.g.:

    /etc/NetworkManager/conf.d/dhcp-client.conf

    [main]
    dhcp=dhclient

Note:

- NetworkManger does not support using dhcpcd for IPv6. See NetworkManager issue #5. If dhcpcd is set as the DHCP client, NetworkManager will use the internal DHCP client for DHCPv6.
- Do not enable the systemd units shipped with the dhclient and dhcpcd packages. They will conflict with NetworkManager, see the note in #Installation for details.

### DNS management

NetworkManager's DNS management is described in the GNOME project's wiki page—Projects/NetworkManager/DNS.

#### DNS caching and conditional forwarding

NetworkManager has a plugin to enable DNS caching and conditional forwarding (previously called "split DNS" in NetworkManager's documentation) using dnsmasq or systemd-resolved. The advantages of this setup is that DNS lookups will be cached, shortening resolve times, and DNS lookups of VPN hosts will be routed to the relevant VPN's DNS servers. This is especially useful if you are connected to more than one VPN.

Note: If `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/stub-resolv.conf`, `/run/systemd/resolve/resolv.conf`,`/lib/systemd/resolv.conf` or `/usr/lib/systemd/resolv.conf`, NetworkManager will choose systemd-resolved automatically. To use dnsmasq, you must first remove that symlink, then restart NetworkManager.

##### dnsmasq

Make sure dnsmasq has been installed. Then set `main.dns=dnsmasq` with a configuration file in `/etc/NetworkManager/conf.d/`:

    /etc/NetworkManager/conf.d/dns.conf

    [main]
    dns=dnsmasq

Now run `nmcli general reload` as root. NetworkManager will automatically start dnsmasq and add `127.0.0.1` to `/etc/resolv.conf`. The original DNS servers can be found in `/run/NetworkManager/no-stub-resolv.conf`. You can verify dnsmasq is being used by doing the same DNS lookup twice with `drill example.com` and verifying the server and query times.

Note:

- You do not need to start `dnsmasq.service` or edit `/etc/dnsmasq.conf`. NetworkManager will start dnsmasq without using the systemd service and without reading the dnsmasq's default configuration file(s).
- The dnsmasq instance started by NetworkManager will bind to `127.0.0.1:53`, you cannot run any other software (including `dnsmasq.service`) on the same address and port.

###### Custom dnsmasq configuration

Custom configurations can be created for dnsmasq by creating configuration files in `/etc/NetworkManager/dnsmasq.d/`. For example, to change the size of the DNS cache (which is stored in RAM):

    /etc/NetworkManager/dnsmasq.d/cache.conf

    cache-size=1000

You can check the configuration file syntax with:

    dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d

See dnsmasq(8) for all available options.

###### IPv6

The factual accuracy of this article or section is disputed.

Reason: This does not solve the issue because NetworkManager does not add `::1` to `/etc/resolv.conf`. Unless `@::1` is manually passed to drill, it will still fail with `Error: error sending query: No (valid) nameservers defined in the resolver`. (Discuss in Talk:NetworkManager)

Enabling `dnsmasq` in NetworkManager may break IPv6-only DNS lookups (i.e. `drill -6 [hostname]`) which would otherwise work. In order to resolve this, creating the following file will configure dnsmasq to also listen to the IPv6 loopback:

    /etc/NetworkManager/dnsmasq.d/ipv6-listen.conf

    listen-address=::1

In addition, `dnsmasq` also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this (Ubuntu Bug). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists.

###### DNSSEC

The dnsmasq instance started by NetworkManager by default will not validate DNSSEC since it is started with the `--proxy-dnssec` option. It will trust whatever DNSSEC information it gets from the upstream DNS server.

For dnsmasq to properly validate DNSSEC, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:

    /etc/NetworkManager/dnsmasq.d/dnssec.conf

    conf-file=/usr/share/dnsmasq/trust-anchors.conf
    dnssec

##### systemd-resolved

This article or section needs expansion.

Reason: NetworkManager 1.16 adds a new setting `main.systemd-resolved`[4] (enabled by default). It unconditionally sends DNS configuration to systemd-resolved. Related to "Preserving resolv.conf" from systemd-resolved#DNS? (Discuss in Talk:NetworkManager)

NetworkManager can use systemd-resolved as a DNS resolver and cache. Make sure that systemd-resolved is properly configured and that `systemd-resolved.service` is started before using it.

systemd-resolved will be used automatically if `/etc/resolv.conf` is a symlink to `/run/systemd/resolve/stub-resolv.conf`, `/run/systemd/resolve/resolv.conf` or `/usr/lib/systemd/resolv.conf`.

You can enable it explicitly by setting `main.dns=systemd-resolved` with a configuration file in `/etc/NetworkManager/conf.d/`:

    /etc/NetworkManager/conf.d/dns.conf

    [main]
    dns=systemd-resolved

##### DNS resolver with an openresolv subscriber

If openresolv has a subscriber for your local DNS resolver, set up the subscriber and configure NetworkManager to use openresolv.

Because NetworkManager advertises a single "interface" to resolvconf, it is not possible to implement conditional forwarding between two NetworkManager connections. See NetworkManager issue 153.

This can be partially mitigated if you set `private_interfaces="*"` in `/etc/resolvconf.conf`[5]. Any queries for domains that are not in search domain list will not get forwarded. They will be handled according to the local resolver's configuration, for example, forwarded to another DNS server or resolved recursively from the DNS root.

#### Custom DNS servers

##### Setting custom global DNS servers

To set DNS servers for all connections, specify them in NetworkManager.conf(5) using the syntax `servers=serveripaddress1,serveripaddress2,serveripaddress3` in a section named `[global-dns-domain-*]`. For example:

    /etc/NetworkManager/conf.d/dns-servers.conf

    [global-dns-domain-*]
    servers=::1,127.0.0.1

Note:

- If you use NetworkManager's dnsmasq or systemd-resolved plugin or openresolv subscribers, then do not specify loopback addresses with the `servers=` option, it can break DNS resolution.
- The specified servers do not get sent to systemd-resolved, the connection's DNS servers are used instead.

##### Setting custom DNS servers in a connection

###### Setting custom DNS servers in a connection (GUI)

Setup will depend on the type of front-end used; the process usually involves right-clicking on the applet, editing (or creating) a profile, and then choosing DHCP type as Automatic (specify addresses). The DNS addresses will need to be entered and are usually in this form: `127.0.0.1, DNS-server-one, ...`.

###### Setting custom DNS servers in a connection (nmcli / connection file)

To setup DNS Servers per connection, you can use the `dns` field (and the associated `dns-search` and `dns-options`) in the connection settings.

If `method` is set to `auto` (when you use DHCP), you need to set `ignore-auto-dns` to `yes`.

#### /etc/resolv.conf

NetworkManager's `/etc/resolv.conf` management mode is configured with the `main.rc-manager` setting. networkmanager sets it to `symlink` as apposed to the upstream default `auto`. The setting and its values are documented in the NetworkManager.conf(5) man page.

Tip: Using openresolv allows NetworkManager to coexists with other resolvconf supporting software or, for example, to run a local DNS caching and split-DNS resolver for which openresolv has a subscriber. Note that conditional forwarding is not yet fully supported when using NetworkManager with openresolv.

NetworkManager also offers hooks via so called dispatcher scripts that can be used to alter the `/etc/resolv.conf` after network changes. See #Network services with NetworkManager dispatcher and NetworkManager(8) for more information.

Note:

- If NetworkManager is configured to use either dnsmasq or systemd-resolved, then the appropriate loopback addresses will be written to `/etc/resolv.conf`.
- The `resolv.conf` file NetworkManager writes or would write to `/etc/resolv.conf` can be found at `/run/NetworkManager/resolv.conf`.
- A `resolv.conf` file with the acquired name servers and search domains can be found at `/run/NetworkManager/no-stub-resolv.conf`.

##### Unmanaged /etc/resolv.conf

To stop NetworkManager from touching `/etc/resolv.conf`, set `main.dns=none` with a configuration file in `/etc/NetworkManager/conf.d/`:

    /etc/NetworkManager/conf.d/dns.conf

    [main]
    dns=none

Tip: You might also want to set `main.systemd-resolved=false`, so that NetworkManager does not send the DNS configuration to systemd-resolved.
Note: See #DNS caching and conditional forwarding, to configure NetworkManager using other DNS backends like dnsmasq and systemd-resolved, instead of using `main.dns=none`.

After that `/etc/resolv.conf` might be a broken symlink that you will need to remove. Then, just create a new `/etc/resolv.conf` file.

##### Use openresolv

Note: NetworkManager does not support using systemd-resolved's resolvconf interface (resolvectl(1) § COMPATIBILITY WITH RESOLVCONF(8)) which is provided by systemd-resolvconf.

- Do not set `main.rc-manager=resolvconf` when using systemd-resolved, instead make sure to correctly create the /etc/resolv.conf symlink or configure NetworkManager to use systemd-resolved explicitly.
- Make sure the systemd-resolvconf package is not installed when systemd-resolved is not used. Unless `systemd-resolved.service` started, it will break all networking software (not just NetworkManager) that use resolvconf.

To configure NetworkManager to use openresolv, set `main.rc-manager=resolvconf` with a configuration file in `/etc/NetworkManager/conf.d/`:

    /etc/NetworkManager/conf.d/rc-manager.conf

    [main]
    rc-manager=resolvconf

### Firewall

You can assign a firewalld zone based on your current connection. For example a restrictive firewall when at work, and a less restrictive one when at home.

This can also be done with NetworkManager dispatcher.

## Network services with NetworkManager dispatcher

There are quite a few network services that you will not want running until NetworkManager brings up an interface. NetworkManager has the ability to start services when you connect to a network and stop them when you disconnect (e.g. when using NFS, SMB and NTPd).

To activate the feature you need to enable and start the `NetworkManager-dispatcher.service`.

Once the service is active, scripts can be added to the `/etc/NetworkManager/dispatcher.d` directory.

Scripts must be owned by root, otherwise the dispatcher will not execute them. For added security, set group ownership to root as well:

    # chown root:root /etc/NetworkManager/dispatcher.d/10-script.sh

Make sure the file has correct permissions:

    # chmod 755 /etc/NetworkManager/dispatcher.d/10-script.sh

The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. 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).

Scripts will receive the following arguments:

- Interface name: e.g. `eth0`
- Action: up, down, vpn-up, vpn-down, ... (see NetworkManager(8) for the complete list)

Warning: 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 dispatcher 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 to be executed. Initially an internal timeout of three seconds only was used. If the called script did not complete in time, it was killed. Later the timeout was extended to about 20 seconds (see the Bugtracker for more information). If the timeout still creates the problem, a work around may be to modify the dispatcher service file `/usr/lib/systemd/system/NetworkManager-dispatcher.service` to remain active after exit:

    /etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf

    [Service]
    RemainAfterExit=yes

Now start and enable the modified `NetworkManager-dispatcher` service.

Warning: Adding the `RemainAfterExit` line to it will prevent the dispatcher from closing. Unfortunately, the dispatcher has to close before it can run your scripts again. With it the dispatcher will not time out but it also will not close, which means that the scripts will only run once per boot. Therefore, do not add the line unless the timeout is definitely causing a problem.

### Dispatcher examples

#### 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 message 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 connection status` or `nmcli connection list`.

    #!/bin/sh
    USER='username'
    REMOTE='user@host:/remote/path'
    LOCAL='/local/path'

    interface=$1 status=$2
    if [ "$CONNECTION_UUID" = "uuid" ]; then
      case $status in
        up)
          SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')
          export SSH_AUTH_SOCK
          su "$USER" -c "sshfs $REMOTE $LOCAL"
          ;;
        down)
          fusermount -u "$LOCAL"
          ;;
      esac
    fi

#### Mounting of SMB shares

Some SMB shares are only available on certain networks or locations (e.g. at home). You can use the dispatcher to only mount SMB shares that are present at your current location.

The following script will check if we connected to a specific network and mount shares accordingly:

    /etc/NetworkManager/dispatcher.d/30-mount-smb.sh

    #!/bin/sh

    # Find the connection UUID with "nmcli connection show" in terminal.
    # All NetworkManager connection types are supported: wireless, VPN, wired...
    if [ "$2" = "up" ]; then
      if [ "$CONNECTION_UUID" = "uuid" ]; then
        mount /your/mount/point &
        # add more shares as needed
      fi
    fi

The following script will unmount all SMB shares before a software initiated disconnect from a specific network:

    /etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh

    #!/bin/sh

    if [ "$CONNECTION_UUID" = "uuid" ]; then
      umount -a -l -t cifs
    fi

Note: Make sure this script is located in the `pre-down.d` sub-directory as shown above, otherwise it will unmount all shares on any connection state change.

The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:

    /etc/NetworkManager/dispatcher.d/40-umount-smb.sh

    #!/bin/sh

    if [ "$CONNECTION_UUID" = "uuid" ]; then
      if [ "$2" = "down" ]; then
        umount -a -l -t cifs
      fi
    fi

Note:

- Since NetworkManager 0.9.8, the pre-down and down events are not executed on shutdown or restart, see this bug report for more info.
- The previous umount scripts are still prone to leaving applications actually accessing the mount to 'hang'.

An alternative is to use the script as seen in NFS#Using a NetworkManager dispatcher:

    /etc/NetworkManager/dispatcher.d/30-smb.sh

    #!/bin/bash

    # Find the connection UUID with "nmcli con show" in terminal.
    # All NetworkManager connection types are supported: wireless, VPN, wired...
    WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"

    if [[ "$CONNECTION_UUID" == "$WANTED_CON_UUID" ]]; then

        # Script parameter $1: NetworkManager connection name, not used
        # Script parameter $2: dispatched event

        case "$2" in
            "up")
                mount -a -t cifs
                ;;
            "pre-down");&
            "vpn-pre-down")
                umount -l -a -t cifs >/dev/null
                ;;
        esac
    fi

Note: This script ignores mounts with the `noauto` option, remove this mount option or use `auto` to allow the dispatcher to manage these mounts.

Create a symlink inside `/etc/NetworkManager/dispatcher.d/pre-down/` to catch the `pre-down` events:

    # ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh

#### Mounting of NFS shares

See NFS#Using a NetworkManager dispatcher.

#### Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in

The idea is to only turn Wi-Fi on when the LAN cable is unplugged (for example when detaching from a laptop dock), and for Wi-Fi to be automatically disabled, once a LAN cable is plugged in again.

Create the following dispatcher script[6], replacing `LAN_interface` with yours.

Note that there is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.

    /etc/NetworkManager/dispatcher.d/wlan_auto_toggle.sh

    #!/bin/sh

    if [ "$1" = "LAN_interface" ]; then
        case "$2" in
            up)
                nmcli radio wifi off
                ;;
            down)
                nmcli radio wifi on
                ;;
        esac
    elif [ "$(nmcli -g GENERAL.STATE device show LAN_interface)" = "20 (unavailable)" ]; then
        nmcli radio wifi on
    fi

Note: You can get a list of interfaces using nmcli. The Ethernet (LAN) interfaces start with `en`, e.g. `enp0s5`

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

Note: This script will require wireless_tools in order to use `iwgetid`.

    /etc/NetworkManager/dispatcher.d/vpn-up

    #!/bin/sh
    VPN_NAME="name of VPN connection defined in NetworkManager"
    ESSID="Wi-Fi network ESSID (not connection name)"

    interface=$1 status=$2
    case $status in
      up|vpn-down)
        if iwgetid | grep -qs ":\"$ESSID\""; then
          nmcli connection up id "$VPN_NAME"
        fi
        ;;
      down)
        if iwgetid | grep -qs ":\"$ESSID\""; then
          if nmcli connection show --active | grep "$VPN_NAME"; then
            nmcli connection down id "$VPN_NAME"
          fi
        fi
        ;;
    esac

If you would like to attempt to automatically connect to VPN for all Wi-Fi networks, you can use the following definition of the ESSID: `ESSID=$(iwgetid -r)`. Remember to set the script's permissions accordingly.

Trying to connect with the above script may still fail with `NetworkManager-dispatcher.service` complaining about 'no valid VPN secrets', because of the way VPN secrets are stored. Fortunately, there are different options to give the above script access to your VPN password.

1: One of them requires editing the 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`.

If that alone does not work, you may have to create a `passwd-file` in a safe location with the same permissions and ownership as the dispatcher script, containing the following:

    /path/to/passwd-file

    vpn.secrets.password:YOUR_PASSWORD

The script must be changed accordingly, so that it gets the password from the file:

    /etc/NetworkManager/dispatcher.d/vpn-up

    #!/bin/sh
    VPN_NAME="name of VPN connection defined in NetworkManager"
    ESSID="Wi-Fi network ESSID (not connection name)"

    interface=$1 status=$2
    case $status in
      up|vpn-down)
        if iwgetid | grep -qs ":\"$ESSID\""; then
          nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file
        fi
        ;;
      down)
        if iwgetid | grep -qs ":\"$ESSID\""; then
          if nmcli connection show --active | grep "$VPN_NAME"; then
            nmcli connection down id "$VPN_NAME"
          fi
        fi
        ;;
    esac

2: Alternatively, change the `password-flags` and 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 save the VPN passwords/secrets again.

#### Use dispatcher to disable IPv6 on VPN provider connections

Many commercial VPN providers support only IPv4. That means all IPv6 traffic bypasses the VPN and renders it virtually useless. To avoid this, dispatcher can be used to disable all IPv6 traffic for the time a VPN connection is up.

    /etc/NetworkManager/dispatcher.d/10-vpn-ipv6

    #!/bin/sh

    case "$2" in
    	vpn-up)
    		echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6
    		;;
    	vpn-down)
    		echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6
    		;;
    esac

#### OpenNTPD

See OpenNTPD#Using NetworkManager dispatcher.

## 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 `NetworkManager.service`.

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 IP addresses, you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.

## Tips and tricks

### Encrypted Wi-Fi passwords

By default, NetworkManager stores passwords in clear text in the connection files at `/etc/NetworkManager/system-connections/`. To print the stored passwords, use the following command:

    # grep -r '^psk=' /etc/NetworkManager/system-connections/

The passwords are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. `nm-applet`).

It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside of using a keyring is that the connections have to be set up for each user.

#### Using GNOME Keyring

The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.

Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME `nm-applet`, run `nm-connection-editor` from a terminal, select a network connection, click `Edit`, select the `Wifi-Security` tab and click on the right icon of password and check `Store the password only for this user`.

#### Using KDE Wallet

Using KDE's plasma-nm, click the applet, click on the top right `Settings` icon, click on a network connection, in the `General settings` tab, untick `all users may connect to this network`. If the option is ticked, the passwords will still be stored in clear text, even if a keyring daemon is running.

If the option was selected previously and you un-tick it, you may have to use the `reset` option first to make the password disappear from the file. Alternatively, delete the connection first and set it up again.

### Sharing internet connection over Wi-Fi

You can share your internet connection (e.g. 3G or wired) with a few clicks. Please note that a firewall may interfere with internet sharing.

You will need a Wi-Fi card which supports AP mode, see Software access point#Wi-Fi device must support AP mode for details.

Install the dnsmasq package to be able to actually share the connection. Note that NetworkManager starts its own instance of dnsmasq, independent of `dnsmasq.service`, as a DHCP server. See #dnsmasq for the caveats.

Create the shared connection:

- Click on applet and choose Create new wireless network.
- Follow wizard (choose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).
  - Choose either Hotspot or Ad-hoc as Wi-Fi mode.

The connection will be saved and remain stored for the next time you need it.

Note: Android does not support connecting to Ad-hoc networks. To share a connection with Android use infrastructure mode (i.e. set Wi-Fi mode to "Hotspot").

### Sharing internet connection over Ethernet

Scenario: your device has internet connection over wi-fi and you want to share the internet connection to other devices over ethernet.

Requirements:

- Install the dnsmasq package to be able to actually share the connection. Note that NetworkManager starts its own instance of dnsmasq, independent of `dnsmasq.service`, as a DHCP server. See #dnsmasq for the caveats.
- Your internet connected device and the other devices are connected over a suitable ethernet cable (this usually means a cross over cable or a switch in between).
- Internet sharing is not blocked by a firewall.

Steps:

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: nm-connection-editor is not a dependency of networkmanager and needs to be installed separately. (Discuss in Talk:NetworkManager)

- Run `nm-connection-editor` from terminal.
- Add a new ethernet connection.
- Give it some sensible name. For example "Shared Internet"
- Go to "IPv4 Settings".
- For "Method:" select "Shared to other computers".
- Save

Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.

### Checking if networking is up inside a cron job or script

This article or section is out of date.

Reason: nm-tool was remove from NetworkManager for long time now[7]. nmcli should be used instead. (Discuss in Talk:NetworkManager)

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.

### Connect to network with secret on boot

By default, NetworkManager will not connect to networks requiring a secret automatically on boot. This is because it locks such connections to the user who makes it by default, only connecting after they have logged in. To change this, do the following:

1. Right click on the `nm-applet` icon in your panel and select Edit Connections and open the Wireless tab
2. Select the connection you want to work with and click the Edit button
3. Check the boxes “Connect Automatically” and “Available to all users”
4. Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected

Log out and log back in to complete.

### OpenConnect with password in KWallet

While you may type both values at connection time, plasma-nm 0.9.3.2-1 and above are 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 username and password accordingly):

    form:main:username%SEP%username%SEP%form:main:password%SEP%password

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 or interface-name by using the following in `/etc/NetworkManager/conf.d/unmanaged.conf`:

    [keyfile]
    unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0

After editing the file, run `nmcli general reload` as root. Afterwards you should be able to configure interfaces without NetworkManager altering what you have set.

### Configuring MAC address randomization

Note: Disabling MAC address randomization may be needed to get (stable) link connection [8] and/or networks that restrict devices based on their MAC Address or have a limit network capacity.

MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.

NetworkManager supports two types MAC Address Randomization: randomization during scanning, and for network connections. Both modes can be configured by modifying `/etc/NetworkManager/NetworkManager.conf` or by creating a separate configuration file in `/etc/NetworkManager/conf.d/` which is recommended since the aforementioned config file may be overwritten by NetworkManager.

Randomization during Wi-Fi scanning is enabled by default, but it may be disabled by adding the following lines to `/etc/NetworkManager/NetworkManager.conf` or a dedicated configuration file under `/etc/NetworkManager/conf.d`:

    /etc/NetworkManager/conf.d/wifi_rand_mac.conf

    [device]
    wifi.scan-rand-mac-address=no

MAC randomization for network connections can be set to different modes for both wireless and ethernet interfaces. See the GNOME blog post for more details on the different modes.

In terms of MAC randomization the most important modes are `stable` and `random`. `stable` generates a random MAC address when you connect to a new network and associates the two permanently. This means that you will use the same MAC address every time you connect to that network. In contrast, `random` will generate a new MAC address every time you connect to a network, new or previously known. You can configure the MAC randomization by adding the desired configuration under `/etc/NetworkManager/conf.d`:

    /etc/NetworkManager/conf.d/wifi_rand_mac.conf

    [device-mac-randomization]
    # "yes" is already the default for scanning
    wifi.scan-rand-mac-address=yes

    [connection-mac-randomization]
    # Randomize MAC for every ethernet connection
    ethernet.cloned-mac-address=random
    # Generate a random MAC for each WiFi and associate the two permanently.
    wifi.cloned-mac-address=stable

See the following GNOME blog post for more details.

### Enable IPv6 Privacy Extensions

See IPv6#NetworkManager.

### Working with wired connections

By default, NetworkManager generates a connection profile for each wired ethernet connection it finds. At the point when generating the connection, it does not know whether there will be more ethernet adapters available. Hence, it calls the first wired connection "Wired connection 1". You can avoid generating this connection, by configuring `no-auto-default` (see NetworkManager.conf(5)), or by simply deleting it. Then NetworkManager will remember not to generate a connection for this interface again.

You can also edit the connection (and persist it to disk) or delete it. NetworkManager will not re-generate a new connection. Then you can change the name to whatever you want. You can use something like nm-connection-editor for this task.

### Using iwd as the Wi-Fi backend

Note: Consider existing issues before switching to iwd.

Enable the experimental iwd backend creating the following configuration file:

    /etc/NetworkManager/conf.d/wifi_backend.conf

    [device]
    wifi.backend=iwd

Alternatively, you can install networkmanager-iwdAUR, a modified package configured to build NetworkManager working exclusively with iwd, with the main difference being that iwd is required and wpa_supplicant can be uninstalled after building.

### Running in a network namespace

If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be use by selected applications), bring the device down before moving it to the namespace:

    $ ip link set dev MY_DEVICE down
    $ ip link set dev MY_DEVICE netns MY_NAMESPACE
    $ ip netns exec MY_NAMESPACE NetworkManager
    ...
    $ ip netns exec MY_NAMESPACE killall NetworkManager

otherwise NetworkManager will later fail to establish the connection with a `device is strictly unmanaged` error.

### Automatically connect to VPN

NetworkManager can be set to automatically connect to a VPN when connecting to the internet, on a per network basis. The VPN connection itself can be added in GNOME's NetworkManager front-end, but to make it automatically use the VPN `nmcli` must be used. Other front-ends might not have this limitation.

First, make sure to make the VPN connection available to all users. In the GNOME this is a matter of checking a box under the `details` tab. Under the `Identity` tab, in the password field, click the icon on the right side in the field, and set it to `Store the password for all users`.

Then find the UUID of the VPN connection, and add that to `connection.secondaries` of the Internet connection:

    # UUID=$(nmcli --get-values connection.uuid connection show name-of-VPN-connection)
    # nmcli connection modify name-of-Internet-connection connection.secondaries "$UUID"

Now when NetworkManager is restarted and you connect to the Internet connection you have configured, you should automatically get connected to the VPN.

## Troubleshooting

### No prompt for password of secured Wi-Fi networks

When trying to connect to a secured Wi-Fi network, no prompt for a password is shown and no connection is established. This happens when no keyring package is installed. An easy solution is to install gnome-keyring. If you want the passwords to be stored in encrypted form, follow GNOME Keyring to set up the gnome-keyring-daemon.

### Network management disabled

When NetworkManager shuts down but the pid (state) file is not removed, you will see a `Network management disabled` message. If this happens, remove the file manually:

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

### Problems with internal DHCP client

If you have problems with getting an IP address using the internal DHCP client, consider using another DHCP client, see #DHCP client for instructions. This workaround might solve problems in big wireless networks like eduroam.

### DHCP problems with dhclient

If you have problems with getting an IP address via DHCP, try to add the following to your `/etc/dhclient.conf`:

     interface "eth0" {
       send dhcp-client-identifier 01:aa:bb:cc:dd:ee:ff;
     }

Where `aa:bb:cc:dd:ee:ff` is the MAC address of this NIC. The MAC address can be found using the `ip link show interface` command from the iproute2 package.

### 3G modem not detected

See Mobile broadband modem#NetworkManager.

### 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. To check if the driver notifies rfkill about the wireless adapter's status, use:

    $ watch -n1 rfkill list all

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 address settings revert to DHCP

Due to an unresolved bug, when changing default connections to a static IP address, `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 address 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 (e.g. "Auto eth0") and uncheck "Connect automatically". Click Apply and close the connection editor.

### Cannot edit connections as normal user

See #Set up PolicyKit permissions.

### Forget hidden wireless network

Since hidden networks 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 also works for any other connection.

### VPN not working in GNOME

When setting up OpenConnect or vpnc connections in NetworkManager while using GNOME, you will 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):

- For OpenConnect: `ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/`
- For VPNC (i.e. Cisco VPN): `ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/`

This may need to be done for any other NM VPN plugins as well, but these are the two most common.

### Unable to connect to visible European wireless networks

WLAN chips are shipped with a default regulatory domain. If your access point does not operate within these limitations, you will not be able to connect to the network. Fixing this is easy:

1. Install crda
2. Uncomment the correct Country Code in `/etc/conf.d/wireless-regdom`
3. Reboot the system, because the setting is only read on boot

### Automatic connect to VPN on boot is not working

The problem occurs when the system (i.e. NetworkManager running as the root user) tries to establish a VPN connection, but the password is not accessible because it is stored in the GNOME keyring of a particular user.

A solution is to keep the password to your VPN in plaintext, as described in step (2.) of #Use dispatcher to connect to a VPN after a network connection is established.

You do not need to use the dispatcher described in step (1.) to auto-connect anymore, if you use the new "auto-connect VPN" option from the `nm-applet` GUI.

### Systemd Bottleneck

Over time the log files (`/var/log/journal`) can become very large. This can have a big impact on boot performance when using NetworkManager, see: Systemd#Boot time increasing over time.

### Regular network disconnects, latency and lost packets (WiFi)

NetworkManager does a scan every 2 minutes.

Some WiFi drivers have issues when scanning for base stations whilst connected/associated. Symptoms include VPN disconnects/reconnects and lost packets, web pages failing to load and then refresh fine.

Running `journalctl -f` as root will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.

    NetworkManager[410]: <info>  (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))

There is a patched version of NetworkManager which should prevent this type of scanning: networkmanager-noscanAUR.

Alternatively, if roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the WiFi connection profile.

### Unable to turn on wi-fi with Lenovo laptop (IdeaPad, Legion, etc.)

There is an issue with the `ideapad_laptop` module on some Lenovo models due to the wi-fi driver incorrectly reporting a soft block. The card can still be manipulated with `netctl`, but managers like NetworkManager break. You can verify that this is the problem by checking the output of `rfkill list` after toggling your hardware switch and seeing that the soft block persists.

The factual accuracy of this article or section is disputed.

Reason: Try to use `rfkill.default_state` and `rfkill.master_switch_mode` (see kernel-parameters.txt) to fix the rfkill problem. (Discuss in Talk:NetworkManager)

Unloading the `ideapad_laptop` module should fix this. (warning: this may disable the laptop keyboard and touchpad also!).

### Turn off hostname sending

NetworkManager by default sends the hostname to the DHCP server. Hostname sending can only be disabled per connection not globally (Issue #584).

To disable sending your hostname to the DHCP server for a specific connection, add the following to your network connection file:

    /etc/NetworkManager/system-connections/your_connection_file

    ...
    [ipv4]
    dhcp-send-hostname=false
    ...
    [ipv6]
    dhcp-send-hostname=false
    ...

### nm-applet disappears in i3wm

If you use the `xfce4-notifyd.service` for notifications you must edit the unit and add the following:

    /etc/systemd/user/xfce4-notifyd.service.d/display_env.conf

    [Service]
    Environment="DISPLAY=:0.0"

After reloading the daemons restart `xfce4-notifyd.service`. Exit i3 and start it back up again and the applet should show on the tray.

### nm-applet tray icons display wrongly

Currently the tray icons of nm-applet are drawn on top of one another, i.e. the icon displaying wireless strength might show on top of the icon indicating no wired connection. This is apparently a GTK3 bug/problem: https://gitlab.gnome.org/GNOME/gtk/issues/1280 .

A patched version of GTK3 exists in AUR, which apparently fixes the tray icon bug: gtk3-classicAUR.

### Unit dbus-org.freedesktop.resolve1.service not found

If `systemd-resolved.service` is not started, NetworkManager will try to start it using D-Bus and fail:

    dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")
    dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.
    dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")

This is because NetworkManager will try to send DNS information to systemd-resolved regardless of the `main.dns=` setting in NetworkManager.conf(5).[9]

This can be disabled with a configuration file in `/etc/NetworkManager/conf.d/`:

    /etc/NetworkManager/conf.d/no-systemd-resolved.conf

    [main]
    systemd-resolved=false

See FS#62138.

### Secrets were required, but not provided

If you attempt to connect to a network using `nmcli device wifi connect SSID password password` and received the following error:

    Error: Connection activation failed: (7) Secrets were required, but not provided

The error can be resolved by deleting the connection profile and creating a new one:

    $ nmcli connection delete SSID
    $ nmcli device wifi connect SSID password password

You can also try disabling MAC address randomization:

    /etc/NetworkManager/conf.d/wifi_rand_mac.conf

    [device]
    wifi.scan-rand-mac-address=no

### WPA Enterprise connection with iwd

If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the iwd backend then you will get the following error from NetworkManager:

     Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)

This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd config file `/var/lib/iwd/essid.8021x` like described in iwd#WPA Enterprise.

### Failed to request VPN secrets

If you get this error:

    Failed to request VPN secrets #1: No agents were available for this request.

It is either because the password is empty or you have to set up PolicyKit permissions.

## See also

- NetworkManager for Administrators Part 1
- Wikipedia:NetworkManager
- NetworkManager official website

Categories:

- Network managers
- Red Hat

Hidden categories:

- Pages or sections flagged with Template:Expansion
- Pages or sections flagged with Template:Accuracy
- Pages or sections flagged with Template:Style
- Pages or sections flagged with Template:Out of date