What You Don’t Know About NetworkManager Part 1: Configuration

It's a D-Bus Party!

A tale of two services…

The “settings service” is a core concept of NetworkManager.  There are two settings services: the system settings service and the user settings service.  These are just D-Bus services that provide stored network configuration to NM and apps like nm-connection-editor, nm-applet, knetworkmanager, and anything else.  The job of a settings service is to store configuration in some manner (GConf, KConfig, keyfiles, ifcfg, /etc/network/interfaces, whatever) and translate that into a format apps understand.  That’s it.

Why are there two of them?  Well, mainly because you don’t want every connection usable by everyone.  Do you want your kids starting your work VPN tunnel to your secret CIA front-company?  Or your metered 3G to watch online cartoons?  Probably not.  Those connections get stored in your user settings service where only you can use them.  But connections that anyone can use, like your home WiFi or ethernet, should be system connections and thus available to everyone.

What uses these services?

First, NetworkManager uses them to get the list of networks which you’ve connected to.  So it can reconnect you to them.  That’s pretty fundamental.  When you connect to a new network, the settings service (usually nm-applet or knetworkmanager) creates a new connection config and sends that to NM, which then connects you.

Second, any application that wants to know about network configuration can.  Note that they cannot read your passwords unless you allow them to via PolicyKit; there’s a good amount of security built into the system to make sure your passwords aren’t discovered and sold off by Nigerian hackers.  nm-connection-editor lets you edit this list through a UI.  nmcli reads this list to show you active connections and their details in the terminal.  An application like Evolution could read the list and start pulling your work email only when you’re connected to the VPN.  The possibilities are endless.

The system settings service is special

Partially because it’s built into NetworkManager, but also because it’s privileged, the system settings service can do stuff the user settings services can’t.  First, it’s trusted because the storage it uses (ifcfg files, /etc/network/interfaces, keyfiles, etc) cannot be modified by normal users.  You have to prove yourself with PolicyKit before you can modify system settings, and in this way unprivileged users can’t mess with your network configuration.

Second, the system settings service is tasked with interpreting your normal distro config files and turning the configuration format you’re familiar with into data all apps can use.  And this is where the magic lies. In a happy rainbow-filled world, NetworkManager can take your configuration stanzas in /etc/network/interfaces or /etc/sysconfig/network-scripts/ifcfg-eth0 and apply them to your network device, and everything works just like you expect it to.  You don’t even know NetworkManager is there.  This intelligence is provided by distro-specific plugins.

Each distro should have a plugin that understands the native configuration format.  We have plugins for SUSE, Debian, Ubuntu, and Red Hat.  There’s also a generic plugin called ‘keyfile’ that writes .ini-style files to /etc/NetworkManager/system-connections and can be used as a backup if any of the plugins you enable are incapable of saving configuration.  Plugins get enabled through the NetworkManager config file, one of /etc/NetworkManager/NetworkManager.conf (the new name) or /etc/NetworkManager/nm-system-settings.conf (the old name).  And you can stack plugins; since the ‘ifupdown’ (Debian/Ubuntu) plugin can’t write out any configuration yet, adding the ‘keyfile’ plugin allows changed connections to be saved as keyfiles instead.

Make the Editor Your Slave

All it really wants is to love you

You don’t have edit the config files directly unless you want to; the connection editor provides a convenient interface to all the network configuration.  But since the system settings service is privileged and writes system-wide configuration you’ll need to be authorized through PolicyKit to change it.  Look for /usr/share/polkit-1/actions/org.freedesktop.network-manager-settings.system.policy to find out which privileges there are and what the default access level is.  Read up on PolicyKit to find out how to customize the privileges for your installation or your organization.  If you can’t change the “Available to all users” checkbox for a connection, chances are you’re not authorized or PolicyKit can’t determine who you are.  You should either fix that, or talk to your system administrator 🙂

So how do I talk to a settings service?

If you’re an app developer, there are three important resources are at your disposal:

  • the NetworkManager setting specification, which details what the connection configuration contains and what values each member has
  • the python examples, which show how to talk to a settings service and get the information you need
  • the mailing list, which provides quick, useful help when you get stuck

Suggestions for better examples and documentation focus greatly appreciated.  It’s not supposed to be hard.  It’s supposed to be fun to add network awareness to your apps.

Tell me more!

No.  Not yet.  Later.  I can only do so much in a week.