ifconfig: add -D option to print driver name for interface

[karels]

Summary

Add -D option to add the drivername and unit number to ifconfig output
for normal display, including -a. Use the inappropriately named ifconfig_get_orig_name() from
libifconfig to fetch the name. Note that this is the original name
for most drivers, but not for some exceptions like epair (which appends
'a' or 'b' to the unit number). epair interface pairs both display
as "epair0", etc.

[rcm]

@kp and I actually discussed this back in June in response to an internal need. In fact, he pointed me towards this exact interface ifconfig_get_orig_name.

If I recall, he had some concerns but that might be overcome with proper documentation which I believe you've done here.

[bz]

Do you have an example output? Depending on how this ocmes out I wonder if we should just display it along with ifconfig -v (or also with)?

[karels]

In D42721#974556, @bz wrote:

Do you have an example output? Depending on how this ocmes out I wonder if we should just display it along with ifconfig -v (or also with)?

I also debated whether this should be standard. Including it with -v seems perfectly reasonable. I just checked -v on my test machine, and it did nothing.

Here is a an example from a virtual machine:

# ifconfig -D bhyve
bhyve: flags=1008843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
        options=80028<VLAN_MTU,JUMBO_MTU,LINKSTATE>
        ether 58:9c:fc:0b:0c:10
        inet 10.0.3.1/24 broadcast 10.0.3.255
        inet6 fe80::5a9c:fcff:fe0b:c10%bhyve prefixlen 64 scopeid 0x1
        inet6 2001:470:c202:3::1 prefixlen 64
        media: Ethernet autoselect (10Gbase-T <full-duplex>)
        status: active
        nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>
        drivername: vtnet0

[bz]

In D42721#974557, @karels wrote:

In D42721#974556, @bz wrote:

Do you have an example output? Depending on how this ocmes out I wonder if we should just display it along with ifconfig -v (or also with)?

I also debated whether this should be standard. Including it with -v seems perfectly reasonable. I just checked -v on my test machine, and it did nothing.

Here is a an example from a virtual machine:

 # ifconfig -D bhyve
 bhyve: flags=1008843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST,LOWER_UP> metric 0 mtu 1500
...
         drivername: vtnet0

I think if you don't need -D specifically I would simply add it to -v.

BTW. WiFi has something similar where cloned interfaces did not reveal the underlying hardware interface anymore and we just (currently always) print it but probably should put it under -v as well then?

wlan99: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
..
        parent interface: iwlwifi0

[kp]

I'd prefer describing this as printing the driver name and unit number. This is often the same as the original interface name, but not always.

At the very least epair and if_ovpn deviate from this pattern, and I suspect there are more exceptions. stf does too, I believe, and tun/tap might as well.
I can see this might be useful sometimes, but I'd object to advertising it as something it is emphatically not (that is: the original interface name).

sbin/ifconfig/ifconfig.8

110

Also if_ovpn:

ovpnc0: flags=8010<POINTOPOINT,MULTICAST> metric 0 mtu 1428
        options=80000<LINKSTATE>
        groups: openvpn
        nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>
        drivername: openvpn0

ovpns1: flags=8010<POINTOPOINT,MULTICAST> metric 0 mtu 1428
        options=80000<LINKSTATE>
        groups: openvpn
        nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL>
        drivername: openvpn1

[bz]

In D42721#974560, @kp wrote:

I'd prefer describing this as printing the driver name and unit number. This is often the same as the original interface name, but not always.

At the very least epair and if_ovpn deviate from this pattern, and I suspect there are more exceptions. stf does too, I believe, and tun/tap might as well.
I can see this might be useful sometimes, but I'd object to advertising it as something it is emphatically not (that is: the original interface name).

And that is one more time a thing I did not understand 20 years ago and now. We added if_xname and split things out but with renaming we should have kept an if_oname (original name).
That said ifconfig_get_orig_name is really a misleading name that probably still comes out of the 20 year old confusion. Maybe we should fix the underlying issue once and for all as well?

[karels]

In D42721#974560, @kp wrote:

I'd prefer describing this as printing the driver name and unit number. This is often the same as the original interface name, but not always.

At the very least epair and if_ovpn deviate from this pattern, and I suspect there are more exceptions. stf does too, I believe, and tun/tap might as well.
I can see this might be useful sometimes, but I'd object to advertising it as something it is emphatically not (that is: the original interface name).

I used -D for "driver name" (and unit number). and the man page describes it as such; it says that this is "normally" the original name. Do you think this is too strong? Should it mention more exceptions? Or are you referring to the commit title?

About -v: I don't have an 802.11 interface, but it sounds like -v is quite verbose. In that case, I think I'd rather use -D or have this standard. It could also display only when it is different than the interface name that was printed. However, there is a certain amount of overhead to ifconfig_get_orig_name().

[karels]

In D42721#974565, @bz wrote:

In D42721#974560, @kp wrote:

I'd prefer describing this as printing the driver name and unit number. This is often the same as the original interface name, but not always.

At the very least epair and if_ovpn deviate from this pattern, and I suspect there are more exceptions. stf does too, I believe, and tun/tap might as well.
I can see this might be useful sometimes, but I'd object to advertising it as something it is emphatically not (that is: the original interface name).

And that is one more time a thing I did not understand 20 years ago and now. We added if_xname and split things out but with renaming we should have kept an if_oname (original name).
That said ifconfig_get_orig_name is really a misleading name that probably still comes out of the 20 year old confusion. Maybe we should fix the underlying issue once and for all as well?

Sorry, my comment and this one crossed. I agree that ifconfig_get_orig_name is misleading, but it has been there since 2017 or so. I'd hate to break things by changing it, and it is deeply hidden so it doesn't matter that much.

[kp]

In D42721#974566, @karels wrote:

In D42721#974560, @kp wrote:

I can see this might be useful sometimes, but I'd object to advertising it as something it is emphatically not (that is: the original interface name).

I used -D for "driver name" (and unit number). and the man page describes it as such; it says that this is "normally" the original name. Do you think this is too strong? Should it mention more exceptions? Or are you referring to the commit title?

The commit title and two comments, yes.

Users are very quick to get wrong ideas into their heads, and once they're in they're impossible to change, so I tend to be a very keen on avoiding giving them such opportunities.

sbin/ifconfig/ifconfig.c

470

And this one.

sbin/ifconfig/ifconfig.h

234

This comment.

[freebsd_igalic.co]

General questions:

• what's the chance to get this folded into -a/-v?
• what's the chance to get this MFC'd to 14/13/12?

[karels]

In D42721#974591, @freebsd_igalic.co wrote:

General questions:

• what's the chance to get this folded into -a/-v?
• what's the chance to get this MFC'd to 14/13/12?

-a is orthogonal, and it works with that now. -a shouldn't change the output for individual interfaces though. It can easily be included with -v, but I'm a little reluctant to do it only with -v. MFC to 14: for sure; 13: probably; 12: only if there is a good reason?

[karels]

There seems to be an unanswered question. Should the driver name be printed

1. With -D only (as now)
2. With -D or -v (so verbose is fully verbose)
3. With -v only (I'm not fond of this one)
4. Anytime the driver name is different than the interface name (including the outliers Kristof mentioned)
5. Always (I considered this. and hopefully scripts wouldn't break. but ...)

[zlei]

In D42721#974631, @karels wrote:

There seems to be an unanswered question. Should the driver name be printed

1. With -D only (as now)
2. With -D or -v (so verbose is fully verbose)

Either one should be OK. I would treat -v as an option for debugging purpose.

1. With -v only (I'm not fond of this one)
2. Anytime the driver name is different than the interface name (including the outliers Kristof mentioned)
3. Always (I considered this. and hopefully scripts wouldn't break. but ...)

I'd prefer Always. Just keep it simple. Do not be too smart.

sbin/ifconfig/ifconfig_netlink.c

440

original -> driver

[zlei]

Back to the report by @freebsd_igalic.co :

but we don't know what it was renamed from, and this only works for *real* interfaces, not for cloned devices, or epairs.

And by @kevans

Just last week I found this quite a pain as well; once an interface has been renamed, if it's not a pseudo-interface with an obvious group there's no clear way, AFAICT, to determine which driver created it without perusing pciconf output or whatnot and hopefully being able to associate the NICs listed with the new names (easier when there's only one NIC, of course). Kind of a pain when you're working on a remote machine that you're not at all familiar with.

I would summarize as following:

1. For physical interfaces, it is absolutely necessary to get its driver name and driver unit. Also sysctl dev.<name>.<unit> would give us additional useful info.
2. For cloned interfaces,
   • lo / bridge / disc / edsc / gif / gre / ipsec / lagg / ovpn / stf / tun / tap / vlan / vxlan , the driver name is useful, but the driver unit is not.
   • epair, both driver name and driver unit are useful. We can infer that two interface is a pair by same driver unit.
   • wireless, we can infer the driver by its parent interface. So it seems its driver name is not useful. For the driver unit, if we have sysctl dev.<name>.<unit> or counterpart then the driver unit is useful.

Also note that the cloned interfaces have groups info ( I'm not sure if wireless have but that is not important, it has parent interface ) which can be used to infer the driver (name).

[kp]

In D42721#974725, @zlei wrote:

Also note that the cloned interfaces have groups info ( I'm not sure if wireless have but that is not important, it has parent interface ) which can be used to infer the driver (name).

It's true that cloned interfaces default to being a member of their corresponding interface group, but bear in mind that this is user-configurable. Users may decide to remove these interfaces from those groups and/or add other interfaces to them. Tools should not attempt to draw conclusions from interface group memberships.

[freebsd_igalic.co]

In D42721#974727, @kp wrote:

Tools should not attempt to draw conclusions from interface group memberships.

I'm gonna have to rethink half of my code here, https://github.com/canonical/cloud-init/blob/main/cloudinit/distros/parsers/ifconfig.py

[karels]

In D42721#974723, @zlei wrote:

In D42721#974631, @karels wrote:

There seems to be an unanswered question. Should the driver name be printed

1. With -D only (as now)
2. With -D or -v (so verbose is fully verbose)

Either one should be OK. I would treat -v as an option for debugging purpose.

1. With -v only (I'm not fond of this one)
2. Anytime the driver name is different than the interface name (including the outliers Kristof mentioned)
3. Always (I considered this. and hopefully scripts wouldn't break. but ...)

I'd prefer Always. Just keep it simple. Do not be too smart.

Any other opinions? I'll probably make the changes tomorrow (today is a holiday in the US). I'm still a little worried about script breakage if the default output changes, but we can try it on main to see if there are complaints.

sbin/ifconfig/ifconfig.c

470

OK, done in my copy pending the next push.

sbin/ifconfig/ifconfig.h

234

OK

sbin/ifconfig/ifconfig_netlink.c

440

This one is reporting an error from ifconfig_get_orig_name, so I used a corresponding name without using the actual function name. It is highly unlikely to appear in output.

[freebsd_igalic.co]

In D42721#974767, @karels wrote:

I'm still a little worried about script breakage if the default output changes, but we can try it on main to see if there are complaints.

i don't think there's a lot of chance of breakable, since we're adding information, not remove or change existing information.

[freebsd_igalic.co]

I've edited the title summary, to be more explicit about original name vs driver name, so we don't forget about this on commit

[karels]

In D42721#974773, @freebsd_igalic.co wrote:

I've edited the title summary, to be more explicit about original name vs driver name, so we don't forget about this on commit

It's best not to edit the title on other's reviews, as the identical change needs to be made in git for updates to work. In this case, I was waiting for consensus on whether -D remains as well.

[zlei]

In D42721#974725, @zlei wrote:

Back to the report by @freebsd_igalic.co :

but we don't know what it was renamed from, and this only works for *real* interfaces, not for cloned devices, or epairs.

And by @kevans

Just last week I found this quite a pain as well; once an interface has been renamed, if it's not a pseudo-interface with an obvious group there's no clear way, AFAICT, to determine which driver created it without perusing pciconf output or whatnot and hopefully being able to associate the NICs listed with the new names (easier when there's only one NIC, of course). Kind of a pain when you're working on a remote machine that you're not at all familiar with.

I would summarize as following:

1. For physical interfaces, it is absolutely necessary to get its driver name and driver unit. Also sysctl dev.<name>.<unit> would give us additional useful info.

Interface name of usb ethernet is ue%u , and the MIB is net.ue.<unit>. It is different from that of PCI ethernet interfaces.

# sysctl net.ue.0
net.ue.0.%parent: ure0

# sysctl dev.ure.0
dev.ure.0.chipver: 7410
dev.ure.0.%parent: uhub1
dev.ure.0.%pnpinfo: vendor=0x0bda product=0x8156 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="401000001" release=0x3104 mode=host intclass=0xff intsubclass=0xff intprotocol=0x00
dev.ure.0.%location: bus=1 hubaddr=1 port=3 devaddr=2 interface=0 ugen=ugen1.2
dev.ure.0.%driver: ure
dev.ure.0.%desc: Realtek USB 10/100/1G/2.5G LAN, class 0/0, rev 3.20/31.04, addr 2

That is since 9b90005109a2 . I guess dev.ue.<unit> is better for those usb ethernet.

1. For cloned interfaces,
   • lo / bridge / disc / edsc / gif / gre / ipsec / lagg / ovpn / stf / tun / tap / vlan / vxlan , the driver name is useful, but the driver unit is not.
   • epair, both driver name and driver unit are useful. We can infer that two interface is a pair by same driver unit.
   • wireless, we can infer the driver by its parent interface. So it seems its driver name is not useful. For the driver unit, if we have sysctl dev.<name>.<unit> or counterpart then the driver unit is useful.

Also note that the cloned interfaces have groups info ( I'm not sure if wireless have but that is not important, it has parent interface ) which can be used to infer the driver (name).

[karels]

update comments to omit "original name"

[karels]

I updated comments, but am waiting for more input before making this behavior the default (or something other than -D).

[freebsd_igalic.co]

In D42721#975425, @karels wrote:

I updated comments, but am waiting for more input before making this behavior the default (or something other than -D).

thank you, and please forgive the faux pas.
I think -D for explicit, and adding it to -a

[karels]

In D42721#975428, @freebsd_igalic.co wrote:

I think -D for explicit, and adding it to -a

I think the format for an individual interface should be the same as for that interface as part of -a. In other words, -D should work with -a, but not be implied by it. That's the way it works in the review as it stands.

[karels]

Print driver name with -v as well as -D. May as well be fully verbose.

[karels]

With the input so far, my inclination is to stay with -D rather than printing the driver name (and unit) by default. I made one small change, which is to print the driver name with -v or -D, so -v is fully verbose.

Any further comments? Can someone approve?

[zlei]

Look good to me.

[zarychtam_plan-b.pwste.edu.pl]

Thank you. It deserves to be called the commit of the month. Would you please do a MFC to stable/14 ?

I am sorry for the noise. The commit message states that MFC is planned, which is fantastic news and will be surely appreciated

[karels]

I did the MFC to stable/14. However, this does not merge to stable/13, which does not use netlink and is otherwise different. It could be done manually, but I won't do it unless there is a reason to do so.