Abstract understanding NetworkManager and nmcli

[Yang Zhang <yanghatespam gmail com>]

Hi, I'm trying to configure NetworkManager via the command line (headless box) and I'm a bit confused as to the "model of the universe" I'm dealing with here, which as far as I've Googled is not documented anywhere.

The NetworkManager/nmcli man pages reference terms like Connection without defining or distinguishing them.  FWIW, I'm coming from the perspective of someone who understands basic "raw" network configuration with e.g. "ip addr add 192.168.0.1/24 dev eth0" for static IP addresses, but doesn't understand what's going on in NetworkManager.

For starters, I'm mainly wonder what Connections are.  I see:

$ nmcli con list 
NAME                      UUID                                   TYPE              TIMESTAMP-REAL                    

RestrictedAccess 2        ce91d821-8bb7-4de2-8736-c5a7b650ff76   802-11-wireless   Wed 15 Aug 2012 01:50:08 PM PDT   
RestrictedAccess 3        3d6c98dd-30b8-49f7-9bc7-b27fae098ffd   802-11-wireless   Sat 13 Oct 2012 04:11:13 PM PDT   

RestrictedAccess 1        05a86600-2ceb-488f-9aed-588a3ae8de79   802-11-wireless   Wed 15 Aug 2012 01:40:24 PM PDT   
Wired connection 2        a22d184d-ab1f-44d7-bb94-f272b6b400a8   802-3-ethernet    Thu 11 Oct 2012 06:25:16 PM PDT   

RestrictedAccess          51402c11-6f32-4c9f-9654-0a997657556c   802-11-wireless   Tue 14 Aug 2012 11:19:07 PM PDT   
Wired connection 1        ccb39d93-6391-436b-846c-d9f0c4623c06   802-3-ethernet    Sat 13 Oct 2012 04:11:13 PM PDT   

I see a "RestrictedAccess" WiFi network I've connected to (via the NetworkManager GUI) which is showing up multiple times.  Then there are "Wired connection" 1 & 2, which suggests a mapping to interfaces (eth0 and eth1).  So what are the Connections?  Are they implicitly created per wired interface and per WiFi network (per distinct AP MAC address) that I've connected to?  Yet I've never really used "Wire connection 2" (eth1) - and also there exists no corresponding file in /etc/NetworkManager/system-connections/:

$ l /etc/NetworkManager/system-connections/

RestrictedAccess    RestrictedAccess 2  Wired connection 1

RestrictedAccess 1  RestrictedAccess 3

Then there's `nmcli con down` and `nmcli dev disconnect` - I'm trying to understand the man pages on these, which say:

- "Deactivate a connection." (will help to understand what Connections are)

- "Disconnect a device and prevent the device from automatically activating further connections without user/manual intervention."

I'm guessing the latter corresponds to the "Disconnect" menu items in the NetworkManager GUI.  What GUI interaction does the former correspond to?  And which one of these corresponds to the "Enable Networking" or "Enable Wireless" check menu items?

And how would I go about editing Connections without going through the GUI (e.g. to set static IP addresses, routes, and other options available via the GUI dialogs)?  I can find various bits and pieces from blog/list posts like http://blog.cone.be/2012/01/11/ubuntu-networkmanager/ and https://lists.ubuntu.com/archives/ubuntu-installer/2011-May/000770.html but is there any sort of reference or documentation to consult about how to create and edit these Connection configuration files (which presumably is what I'd need to do)?  If this documentation doesn't exist today is any in the works?  Or are there any suggestions of alternative tools that may currently be better suited for GUI-less environments?

Thanks in advance for any explanations or pointers to resources I may have missed.

-- 

Yang Zhang

http://yz.mit.edu/