From Fedora Project Wiki
No edit summary
 
(15 intermediate revisions by 3 users not shown)
Line 5: Line 5:


== Owner ==
== Owner ==
* Name: [[User:dcbw| Dan Williams]]
* Name: [[User:dcbw| Dan Williams]], Jirka Klimes
* Email: dcbw@redhat.com
* Email: dcbw@redhat.com, jklimes@redhat.com


== Current status ==
== Current status ==
* Targeted release: [[Releases/12 | Fedora 12 ]]  
* Targeted release: [[Releases/13 | Fedora 13 ]]  
* Last updated: 2009-07-26
* Last updated: 2010-02-16
* Percentage of completion: 0%
* Percentage of completion: 100%
 
* [http://koji.fedoraproject.org/koji/buildinfo?buildID=152618 NetworkManager-0.8.0-0.1.git20100122.fc13] has the initial release of nmcli
The current plan for this feature is that it will be implemented during September, thus it will be too late for an advertised feature of F12. It will likely appear in F12 after release.
** 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 ==
== Detailed Description ==
There is no reason that NetworkManager can not be controllable via commandline tools.
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).
This will be very useful to interact with NetworkManager from initscripts, and on servers. 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.


There are two use cases:
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)
* 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.
* 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 ==
== 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
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...
about the 'dumbing down' of Linux...


== Scope ==
== Scope ==
NetworkManager and nm-applet already provide comprehensive dbus 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
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.
the NetworkManager APIs.


== How To Test ==
== How To Test ==
Use ''TOOLNAME'' to control various aspects of NetworkManager functionality. List connections, find out detailed information about connections, bring connections up and down.  
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.


This section needs to be fleshed out further in parallel to writing the ''TOOLNAME(1)''
man page.
== User Experience ==
== User Experience ==
<!-- If this feature is noticeable by its target audience, how will their experiences change as a result?  Describe what they will see or notice. -->
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 ==
== Dependencies ==
Line 46: Line 46:


== Documentation ==
== Documentation ==
None yet.
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 <uuid | ???> [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 <iface> [disconnect | specific options]
** alone it just shows short status of all devices
** 'dev <iface>' shows detailed status like stuff in nm-tool
** wifi device-specific options
*** list - show scan list
*** apinfo <hwaddr> - show detailed AP information


== Release Notes ==
== Release Notes ==
Fedora 12 introduces ''TOOLNAME'', which is a tool that allows to control NetworkManager from the commandline. See the ''TOOLNAME(1)'' man page for more information.
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 ==
== Comments and Discussion ==
* See [[Talk:Features/YourFeatureName]]   
* See [[Talk:Features/NetworkManagerCmdline]]   
 


[[Category:FeaturePageIncomplete]]
[[Category:FeatureAcceptedF13]]

Latest revision as of 18:14, 16 February 2010

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 <uuid | ???> [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 <iface> [disconnect | specific options]
    • alone it just shows short status of all devices
    • 'dev <iface>' shows detailed status like stuff in nm-tool
    • wifi device-specific options
      • list - show scan list
      • apinfo <hwaddr> - 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