Features/NetworkManagerCmdline

= NetworkManager commandline tools =

Summary
Control NetworkManager without a GUI

Owner

 * Name: Dan Williams, Jirka Klimes
 * Email: dcbw@redhat.com, jklimes@redhat.com

Current status

 * Targeted release: Fedora 13
 * Last updated: 2010-02-16
 * Percentage of completion: 100%
 * NetworkManager-0.8.0-0.1.git20100122.fc13 has the initial release of nmcli
 * Done: status, connection list, device list, wifi AP list, connect/disconnect
 * ToDo: clean up formatting, terse output, fix command names, implement the rest of the spec

Detailed Description
There is no reason that NetworkManager can not be controllable via commandline tools; it can already be controlled from any D-Bus enabled tool including directly with dbus-send. But it would be a lot easier to use from a terminal, headless machine, or the initscripts with a proper CLI client. To make the commandline tools usable in these situations they should be lightweight and have a small footprint. Therefore, tools written in C will be preferable over Python scripts (like cnetworkmanager).

There are three use cases:
 * Initscripts: for NetworkManager-controlled connections ifup/ifdown should simply poke NetworkManager instead of having both tools step on each other's toes.
 * Server: In this case, the tool should talk directly to NetworkManager and control only system-wide connections. Basic functionality to cover: ifup/ifdown, list connections, find out details about connections (connection type, speed, uptime, etc)
 * Session: For this case, we might want the tool to talk to nm-applet to find user connections. It can still talk directly to NetworkManager for manipulating these connections. This may then cause the applet to pop up keyring dialogs when secrets are needed. Giving the tool direct access to user configuration data in gconf and secrets in gnome-keyring will be much more complicated and is probably out of scope for the first version.

Benefit to Fedora
NetworkManager becomes more suitable on servers, bringing Fedora closer to a consolidated network configuration. Power users will have one less reason to complain about the 'dumbing down' of Linux...

Scope
NetworkManager and nm-applet already provide comprehensive D-Bus APIs. The remaining task is simply to write a tool that offers commandline access to this API in a way that makes sense. An important side-effect of this should be to produce documentation for the NetworkManager APIs.

How To Test
Use nmcli to control various aspects of NetworkManager functionality. List connections, find out detailed information about connections, bring connections up and down.

This section needs to be fleshed out further in parallel to writing the nmcli(1) man page.

User Experience
Users comfortable with the command-line or who prefer to use a terminal instead of a mouse should be able to easily inspect and control their network connections via a simple /sbin/ip-like tool.

Dependencies
None.

Contingency Plan
Fall back on the existing cnetwork-manager package for commandline control of NetworkManager.

Documentation
Command line interface is expected to follow the /sbin/ip model. The rough outline is expected to be:


 * just typing 'nmcli' shows help/manpage
 * stat/status
 * shows general NM connection status
 * which connections are active
 * which connection (if any) is the "default" connection
 * what type they are
 * what the overall NM connected status is
 * con  [up | down] [--nowait]
 * alone it details the connection
 * whether it's active or not
 * prints out all the settings (but not secrets)
 * up/down should have a "--nowait" option that just exits, otherwise they should block until the operation is done, possibly printing status information while that is happening
 * dev [disconnect | specific options]
 * alone it just shows short status of all devices
 * 'dev ' shows detailed status like stuff in nm-tool
 * wifi device-specific options
 * list - show scan list
 * apinfo - show detailed AP information

Release Notes
Fedora 13 introduces nmcli, which is a tool that allows control of NetworkManager from the commandline. See the nmcli(1) man page for more information.

Comments and Discussion

 * See Talk:Features/NetworkManagerCmdline