GNOME Bugzilla – Bug 682056
tracker: Make 'nmcli' a powerful and consistent CLI tool to control NetworkManager
Last modified: 2014-07-30 16:26:47 UTC
The current CLI for NetworkManager, 'nmcli', should be improved, ideally in a backwards-compatible way, to provide a consistent user interface. The following objectives should be reached: 1) nmcli's object/operation syntax should be consistent, easy to use, and easy to extend Programs like 'ip', 'git', 'vzctl', 'emerge' are examples that could be followed in various ways. 2) nmcli's value syntax should be consistent for both setting and displaying E.g. there shoudn't be one option with true/false and another with on/off. I personally prefer on/off for everything human readable. 3) nmcli should allow creating temporary (unsaved) connections and to save them later vzctl is an example of a usable syntax. It should be decided whether to also allow temporary modifications of permanent connections. This could also be a use case for virtualization platforms that need to make changes, test them and then commit or rollback the configuration. Both CLI and D-Bus APIs would deserve some written guidelines. D-Bus API changes must occur in a backwards compatible manner. CLI should. Carefully planned cleanups should be used for long-term API/CLI maintainance.
*** Bug 645318 has been marked as a duplicate of this bug. ***
Created attachment 222745 [details] a first sketch of sensible nmcli interface Please post your comments on this basic sketch of how nmcli UI should work in my opinion.
Created attachment 222746 [details] a first sketch of sensible nmcli interface Just uploading as text/plain for convenience
Created attachment 222747 [details] An improved version of nmcli syntax sketch.
Created attachment 222756 [details] proposed nmcli syntax sketch More verbose version.
Created attachment 222757 [details] proposed nmcli syntax sketch Added 'nmcli connection restore --all'
(In reply to comment #0) > E.g. there shoudn't be one option with true/false and another with on/off. I > personally prefer on/off for everything human readable. Following the IRC discussion I would suggest just 1/0 for EVERYTHING and not bother with the English meaning too much. > 3) nmcli should allow creating temporary (unsaved) connections and to save them > later > > vzctl is an example of a usable syntax. It should be decided whether to also vzctl? URL? > Both CLI and D-Bus APIs would deserve some written guidelines. D-Bus API > changes must occur in a backwards compatible manner. CLI should. Carefully > planned cleanups should be used for long-term API/CLI maintainance. Why not to write manpage first? (documentation-driven development?)
> Following the IRC discussion I would suggest just 1/0 for EVERYTHING and not > bother with the English meaning too much. I'm more inclined to either yes/no or on/off and less to programmer's true/false or 1/0. But it might be a good idea to accept all of them and print just what happens to be more convenient. > vzctl? URL? http://wiki.openvz.org/Man/vzctl.8 > Why not to write manpage first? (documentation-driven development?) This might actually be a good idea. But we'll be implementing backend stuff step by step and we will need to ship a manpage that reflects the current development status. Many of the things in my syntax specification are not yet implemented or are just broken.
(In reply to comment #6) > Created an attachment (id=222757) [details] > proposed nmcli syntax sketch > > Added 'nmcli connection restore --all' conn[ection] add -> create change -> modify activate|up <uuid/id> [dev[ice] <ifname>] OR activate|up -> up to allow single-char abbreviations (which are extremely convenient with ip), like: nm c a <...> nm c m <...> nm c c <...> > wwan (what's that?) IMHO it is mobile broadbant, GPRS or similar connections.
Comment on attachment 222757 [details] proposed nmcli syntax sketch > wwan (what's that?) "Wireless WAN" aka mobile broadband. (We should probably not call it that any more though since that name ought to also include WiMAX...) > dev[ice] up <ifname> (brings up default connection on ifname) down <ifname> (equivalent to conn down on ifname's connection) >nm connection add --activate type wifi ssid Test psk VerySecretPassword should maybe be a way to prompt for the password instead of passing it on the command line too
> conn[ection] > add -> create > change -> modify This would actually make us different from ip which is not so good. > activate|up <uuid/id> [dev[ice] <ifname>] > OR > activate|up -> up It's actually 'up' currently, it might be just good enough. > to allow single-char abbreviations (which are extremely convenient with ip), > like: > nm c a <...> > nm c m <...> > nm c c <...> Sure. > > > wwan (what's that?) > > IMHO it is mobile broadbant, GPRS or similar connections. OK.
> > wwan (what's that?) > > "Wireless WAN" aka mobile broadband. (We should probably not call it that any > more though since that name ought to also include WiMAX...) It could also by wifi if I'm connecting directly to the provider :). What about 'mobile'? > > dev[ice] > > up <ifname> (brings up default connection on ifname) > down <ifname> (equivalent to conn down on ifname's connection) Added. > >nm connection add --activate type wifi ssid Test psk VerySecretPassword > > should maybe be a way to prompt for the password instead of passing it on the > command line too Definitely.
Created attachment 222808 [details] proposed nmcli syntax sketch
Created attachment 223065 [details] Alternative proposal more resembling 'ip link' There are some changes in this variant that makes it closer to ip-link(8). This could be even nicer to use. Examples: nmcli connection set <conn> up nmcli device set eth0 down
Created attachment 223067 [details] Alternative proposal more resembling 'ip link' Same but text/plain for your convenience.
Something I do very often: $ nmcli dev --help Error: 'dev' command '--help' is not valid. might be nice to parse --help exactly like we parse "help".
Might also be nice not to require the 'nm' argument for stuff like: nmcli nm wifi off at least for "wifi", "wwan", "wimax", "sleep", and "enable". I always find myself typing "nmcli wifi off" and forgetting the "nm".
Two points: 1) nmcli con up MYWIFIID couldn't we make id (and quotes ... I am not sure they are required or not) optional? 2) I would like to be able to switch on VPN even when it asks for a password
> 1) nmcli con up MYWIFIID > couldn't we make id (and quotes ... I am not sure they are required or not) > optional? It is, in the proposal, isn't it? > 2) I would like to be able to switch on VPN even when it asks for a password Sure. Some level of interactivity is expected.
Reading through the comments and the proposal: From reading the initial comment, re "ip and git": iproute and git are not always the most user-friendly CLIs, IMO. In git's case, it's mostly because the interface has built up over a period of time and extended randomly; hopefully that can be avoided some here. In ip's case, it's usally just a matter of how the usage paradigm for the unfamiliar is: $ ip help <reads> $ ip <command> help <reads more> i.e, it's always a two-stage process. Furthermore, /sbin/ip's attempts to be 'smart' (for example: ip help, ip --help, ip -help, all do the same thing, as does 'ip add', 'ip addre', 'ip address'; similarly, it sometimes assumes verbs if you leave them out), make it actually more hostile in that scripts get written that use lazier syntax that then breaks with later releases as more features get added. From the proposal: - Some discussion of what it means to delete a runtime connection, versus just downing the same connection, might be nice. They appear to be overlapping operations. - I don't see anything here about extending configuration to include IP settings. Is this intentional, or intended for a future release? - --ask for credentials also needs applied to connection up, not just creation
> In git's case, it's mostly because the interface has built up over a period of > time and extended randomly; hopefully that can be avoided some here. Thanks. That's the exact purpose of my report. > In ip's case, it's usally just a matter of how the usage paradigm for the > unfamiliar is: > > $ ip help > <reads> > $ ip <command> help > <reads more> We also have reasonably good manpages for iproute now, they have been added earlier this year. I prefer them over the integrated help and I thought this might work just as well for NetworkManager. > i.e, it's always a two-stage process. Furthermore, /sbin/ip's attempts to be > 'smart' (for example: ip help, ip --help, ip -help, all do the same thing, as > does 'ip add', 'ip addre', 'ip address'; similarly, it sometimes assumes verbs > if you leave them out), make it actually more hostile in that scripts get > written that use lazier syntax that then breaks with later releases as more > features get added. We expect nmcli to be used both in scripts and by the users. Human users really like shortcuts. > - Some discussion of what it means to delete a runtime connection, versus just > downing the same connection, might be nice. Yes, we have discussed this a lot with regard to temporary connection configuration and it very much depends on the internals of NetworkManager and API decisions. CLI will be part of it. > They appear to be overlapping operations. In the current model they aren't the same, but we expect the model to actually change. > - I don't see anything here about extending configuration to include IP > settings. Is this intentional, or intended for a future release? Ah, thanks. We were discussing this and there seem to be two possibilities. 1) Mimic 'ip address add' in some way. 2) Pick the ip addresses from the kernel when users actually use 'ip address add'. This may or may not be a good idea. > - --ask for credentials also needs applied to connection up, not just creation True. I tend to think that --ask might be a global nmcli option. Thanks!
(In reply to comment #21) > > - I don't see anything here about extending configuration to include IP > > settings. Is this intentional, or intended for a future release? > > Ah, thanks. We were discussing this and there seem to be two possibilities. > > 1) Mimic 'ip address add' in some way. > > 2) Pick the ip addresses from the kernel when users actually use 'ip address > add'. This may or may not be a good idea. Thinking about what I suspect a user would want , it would be to configure the IP for the specific connection configuration via a nmcli command, as opposed to having the IP configuration attached to the conncetion configuration as a side effect. This especially would be used as a method of doing 'offline' configuration without activating it.
> Thinking about what I suspect a user would want , it would be to configure the > IP for the specific connection configuration via a nmcli command, as opposed to > having the IP configuration attached to the conncetion configuration as a side > effect. This especially would be used as a method of doing 'offline' > configuration without activating it. We expect users to do two distinct things... 1) Change the current network status. User usually use devices for this, not connections. 2) Change the on-disk (or maybe even in-memory in very specific cases, we have not agreed yet) connection configuration. This is probably what you are talking about. In addition, users may want to do both of the above at the same time. The question is... how all these use cases will fit together and how a reasonably consistent CLI should look like.
I should also add DNS modifications to the proposal...
(In reply to comment #16) > Something I do very often: > > $ nmcli dev --help > Error: 'dev' command '--help' is not valid. > > might be nice to parse --help exactly like we parse "help". help is now parsed to allow more variants: c8974bc32de12ddbe280f12c3832f580b69cf0d4 (master)
(In reply to comment #17) > Might also be nice not to require the 'nm' argument for stuff like: > > nmcli nm wifi off > > at least for "wifi", "wwan", "wimax", "sleep", and "enable". I always find > myself typing "nmcli wifi off" and forgetting the "nm". Although it should not be a problem and, at first I thought it's a good idea, now I tend to not allow command-leaving. With command shortening, we will easy get ambiguous input and it will cause more problems than it solves. e.g. nmcli nm wifi nmcli n w nmcli w if we later introduce new command/object, we have problems.
(In reply to comment #18) > 1) nmcli con up MYWIFIID > couldn't we make id (and quotes ... I am not sure they are required or not) > optional? quotes are not needed (only when connection name contains spaces) And I think we could remove id/uuid parameters. But for backwards compatibility we will make them optional, I guess.
A few notes/remarks/ideas to nmcli proposal: 1) I prefer the first proposal. I don't think we have to follow 'ip' that much. And e.g. nmcli connection up <name> looks better for me then nmcli connection set up <name> When we talk about that I prefer up/down to other forms like "activate", etc. First we already use them, and they are short and clear. 2) nmcli s[tatus] I would prefer some other command than "status", because it is/can be used for other stuff too. I suggest "general". 3) nmcli r[eport] is not necessary at all. The functionality is present in other nmcli commands. 4) wwan I agree we could use "mobile" instead. 5) As for booleans yes/no on/off up/down in status (general) I like on/off.
I'm marking the attachments obsolete as they no longer reflect the current development. You can still view them. Part of the important CLI changes is already in the master branch, other important changes are comming or can be seen in the cli-enhance branch. You can use this bug as a tracker for any CLI enhancement bugs for now.
NM bugzilla reorganization... sorry for the bug spam.
is this bug still doing anything useful?
Not for me, closing.