Inconsistency in station local address functions IPv4 vs IPv6 (alpha 3)

[sgryphon]

Board

m5stack-core2

Device Description

M5Stack Core2 ESP32 IoT Development Kit for AWS IoT Kit, https://shop.m5stack.com/products/m5stack-core2-esp32-iot-development-kit-for-aws-iot-edukit?variant=37687799251116

Hardware Configuration

Just the M5Stack Core2

Version

latest master (checkout manually)

IDE Name

PlatformIO

Operating System

Ubuntu 22.04

Flash frequency

240Mhz

PSRAM enabled

yes

Upload speed

115200

Description

Issue

The localIPv6() and globalIPv6() accessors in WiFiSTA.h are implemented inconsistently with how localIP() is implemented, and how localIP() and remoteIP() are used in WiFiClient.h.

What should happen

• globalIPv6() should be removed
• localIP() should continue to return the local host global scope IPv4 address
• localIPv6() should change to be consistent and return the local host global scope IPv6 address, if available
• If a global scope IPv6 address is not available, then localIPv6() should return (in priority order) a local host ULA IPv6 address, or a local host link-local scope IPv6 address.
  • This is consistent with localIP() which may return the local host link-local scope IPv4 address (if there is no global scope IPv4 and link-local IPv4 is enable in LWIP)
• Some mechanism should be provided to get the other additional IPv6 addresses

Mechanism for additional IPv6 addresses

Ideally:

• For additional IPv6 addresses, change the signature to IPAddress localIPv6(uint8_t address_no = 0), similar to dnsIP(dns_no).
  • Return prioritised as above, with 0 (i.e. just default localIP()) returning global scope if available
  • 1, 2, etc returning subsequent addresses
  • Once addresses have run out, return empty result.
  • Common scenario examples:
    a. Single global scope IPv6 address, 0 = global scope address, 1 = link-local scope address
    b. No global scope IPv6 address, 0 = link-local scope address

Alternative:

• Add globalScopeIPv6() to return a global scope IPv6 (same as current globalIPv6())
  • May not have have a global scope IPv6 address if not available on the network (e.g. no RA)
• Add linkScopeIPv6() to return a link-local scope IPv6 (same as current localIPv6())
  • This avoids using the term 'local' with a different meaning; linkLocalScopeIPv6() address could be another option, which uses the correct name and does not have inconsistent use of 'local', but may still cause confusion. linkScopeIPv6() completely avoids the use of the word 'local'.
  • A node will always have a link-local IPv6 (if IPv6 is enabled), as it is auto-configured.
• A drawback of this approach is it only gets 2 addresses when there may be more

Sketch

No directly relevant; the issue is inconsistent naming.

Debug Message

n/a

Other Steps to Reproduce

Background

The new (alpha 3) code in WiFiSTA.h header has several accessors to get the different IP addresses of the local station:

    IPAddress localIP();
    IPAddress localIPv6();
    IPAddress globalIPv6();

This is only alpha, so it would be good to see the naming here fixed before release.

However the usage of the terms here is inconsistent, with some confusion between local as opposed to remote and the concept of link-local addresses.

For comparison WiFiClient.h header (and WiFiUdp.h) has the following accessors, representing a connection where localIP() is the local end and remoteIP() is the remote end:

    IPAddress remoteIP() const;
    IPAddress localIP() const;

As IPAddress now supports IPv6, these connection address could be a local, and remote, IPv6 address, or IPv4.

The WiFiSTA.h accessor of localIP() is similar, in that it represents the local (as opposed to remote), usually an IPv4 private network address, e.g. 192.168.0.x. In the current implementation it is limited to IPv4 addresses.

Whilst it happens to usually be a private address range, a company with a public IPv4 address allocation could use it for WiFi, and the LWIP option CONFIG_LWIP_AUTOIP could also allow the device to self-assign an address in the IPv4 local-link range 169.256/16 range (see RFC 3927).

So localIP() could be a private IPv4 address, global IPv4 address, or a link-local IPv4 address.

However localIP() does not give you IPv6 addresses, even if they are the only ones available (e.g. IPv6 only network).

There is a localIPv6() accessor, however it appears to have been misinterpretted as being for link-local addresses only, an apparent confusion between local and link-local. This is inconsistent with the IPv4 version which is usually a private or global address (but could be link local).

Further the confusing accessor globalIPv6() has been introduced.

To show the best/most appropriate local address client code needs to check globalIPv6() first, then localIP(), then localIPv6(), when all they want to know is what is their IP address.

Only allowing a single return result is probably okay for IPv4, where multiple addresses are rare, but for IPv6 not only is it common to have at least two addresses (you keep your link-local address when you acquire a global one), but it is also common to have multiple global addresses (although LWIP doesn't yet support DHCPv6 or private extensions, so commonly will only have 2).

I have checked existing issues, online documentation and the Troubleshooting Guide

• I confirm I have checked existing issues, online documentation and Troubleshooting guide.

Historical note - original suggestions:

• localIPv6() and globalIPv6() should be removed
• localIP() should return the most relevant IPAddress, of any type, for the station, i.e. same as localIP() for WiFiClient.h, it could be IPv6 or IPv4.
• The priority order should be, if available: global IPv6 address, global IPv4 address, link-local IPv6 address, link-local IPv4 address, or the empty address.
• This means on any IPv4 only network, or when enableIPv6() is not set, localIP() will always return an IPv4 address (backwards compatible).
• Only an IPv6-only system, localIP() will return the local (as opposed to remote) IPv6 address, with a preference for a global IPv6 address, if available, over a link-local address.

[P-R-O-C-H-Y]

@me-no-dev Please take a look as you are working on the network refactoring.

[TD-er]

What should happen
localIPv6() and globalIPv6() should be removed

Nope!

I can somewhat agree to the idea that localIP() should return the preferred type, but then there should be an extra function (or a type parameter for localIP() ) to get the IPv4 address specifically.

You still should be able to get the IPv6 info without having to revert to ESP-IDF functions.

[me-no-dev]

Client.localIP() have nothing to do with IF.localIP(). For Client this is the local IP of the socket. It could be v4 or v6. Same goes for remoteIP(). Those have a really different meaning.

I do not agree that anything needs changing. Interface can have different IPs, so we allow them to be queried. Sockets have specific IPs.

[TD-er]

The signature should be changed to IPAddress localIP(uint8_t address_no = 0), similar to dnsIP(dns_no)

Rather use an enum type.
Especially if you want to use "0" as the preferred type. ("0" could then be the "preferred" type)
You should be able to just ask for a specific type (ipv4/IPv6 link local/IPv6 global) and not having to loop over all available IPs to finally get some that looks like a global or local IPv6.

Client.localIP() have nothing to do with IF.localIP(). For Client this is the local IP of the socket. It could be v4 or v6. Same goes for remoteIP(). Those have a really different meaning.

And this does work perfectly fine.
Whenever I connect to my ESP node via IPv4 or IPv6 (local or global), the client IP is from the same type as what I'm accessing.

[sgryphon]

I guess I'm asking for two things here, one I think I have agreement and the other not.

(1) usage of the term local (and global)
(2) distinction between IPv6 and IPv4

#1 is the more important item.

For #2 for your local address, having separate methods for IPv6 and IPv4 is acceptable. They are not of a lot of use, except for diagnostics, and then you often want to separate out nice headings for them. So if people want to keep localIP() and localIPv6() separate that may be okay.

However for #1, the usage of globalIPv6 and then saeparate localIPv6 to mean link-local is just wrong. localIPv6() should work like localIP() and give you the IPv6 address (a global one if available), of the local station.

(If you do want separate methods to give you global and link-local of the local station, then call then globalIPv6() and linkLocalIPv6() ... don't use localIP() and localIPv6() to mean different things for local. Note that localIP(), the IPv4 version, actually gives you a global address).

The integer parameter (default 0) wasn't meant to be an enum or preferred indicator, but an index, because you may have, for example, 3 IPv6 addresses, so localIPv6(0) would get you the first, localIPv6(1) the second, and locaIPv6(2) the third. Calling localIPv6(3) or more would return empty. This is similar to how dnsIP(int) works.

The ordering of the source addresses, even if limited to IPv6 only, should ideally follow RFC 6724. Even if you don't follow this ordering, you should still be able to access all the IPv6 addresses.

[TD-er]

(If you do want separate methods to give you global and link-local of the local station, then call then globalIPv6() and linkLocalIPv6() ... don't use localIP() and localIPv6() to mean different things for local. Note that localIP(), the IPv4 version, actually gives you a global address).

The last part of your remark does illustrate why it doesn't make things more clear.
So IMHO localIP() as function name for the generic call to get the preferred IP for this node may even be wrong, just for the simple fact that this might also return a global IPv4 address if the interface doesn't have a local IPv6 (is this even possible?)
After all the preference only differentiates between IPv4 and IPv6.

For IPv4 there isn't really a difference between global and local IP. Sure some ranges will not ever be routed to the internet and there is also a range for "zeroconf" IPv4.

For #2 for your local address, having separate methods for IPv6 and IPv4 is acceptable. They are not of a lot of use, except for diagnostics, and then you often want to separate out nice headings for them. So if people want to keep localIP() and localIPv6() separate that may be okay.

But for diagnostics and some specific use cases where you really want to get the IPv4 address, you should still have some function to get the IPv4 address.
For example in my p2p protocol, I do announce the host in the network so others know how to reach it.
This does require both the IPv4 and IPv6 address to be present in the message, regardless of my preferred IPv4/IPv6 setting. This allows hosts to pick whatever IP they prefer (or can use).

For this I don't want to loop through several function calls until I have the IPv4 type.
So with your proposal, I either need to go through this loop or need to have a separate localIPv4() function.
But this is also a bad name as we already concluded since for IPv4 it can also be "global".

Like I said, I do understand why it might be useful to have a single function to return an IP address based on the preferred type.
But I don't agree with the suggested changes as they seem to complicate things in such a way which seems to be not necessary.

[sgryphon]

So IMHO localIP() as function name for the generic call to get the preferred IP for this node may even be wrong, just for the simple fact that this might also return a global IPv4 address if the interface doesn't have a local IPv6 (is this even possible?)

There seems to be a lot of confusion here.

Location of address:

• Local = my computer / current node. These are all the addresses on my network interface(s) used for outgoing connections and/or receiving incoming connections.
• Remote = other computer / other node

Categories of addresses (applies to both IPv6 and IPv4)

• Link-local = scoped only the the local network, e.g. IPv4 169.254.0.0/16 network (RFC 3927), or IPv6 fe80:: network.
• Private range (IPv4 only)
• Global = generally assigned from higher up and routeable to other networks (exact definition varies)

An IPv4 connection between two nodes might use link-local addresses, your "local link-local" address might be 169.254.0.1 which connects to a "remote link-local" address of 169.254.0.2. From the other nodes point of view local & remote are reversed (but both are still link-local).

There appears to be some confusion of using the word local as a short hand reference to link-local, which is just confusing.

[sgryphon]

For IPv4 there isn't really a difference between global and local IP.

That statement makes no sense; even if you mean between global and link-local, it still makes no sense.

Here are the local addressess for my laptop.

• 169.254.227.185/16 ... scope link is an IPv4 local link-local address
• 192.168.1.209/24 ... scope global is an IPv4 local global address (global scope as defined by RFC 6724)

Yes, an IPv4 address can be both local (as opposed to remote) and global (as a scope), but you can also have a local (as opposed to remote) and link-local (as a scope) address.

Other computers on the network, which are (from my point of view) remote, could also have remote link-local and remote global destination addresses.

[TD-er]

I didn't think anyone would still actually be using those 169.254 addresses.

Just to be sure, I checked several of my machines here (Windows/Linux) and none is using 169.254.x.x
I know it was once introduced as some kind of zero-conf idea, but I always thought it never caught on as it became almost synonym for "Whenever you see that, you have got a problem with your network".

Anyway, like I said I can understand the desire to have a single function to get the preferred IP type of your host's IP-address. (deliberately not calling it 'local' to avoid confusion here)
But IMHO this would require an extra function to get the IPv4 address and still functions to get localIPv6 and globalIPv6.
Probably those last 2 should need some index if you want to fetch them all.
Not sure if it would make sense to have multiple IPv4, unless we're talking about IP per interface.

With SPI Ethernet devices, you can have multiple Ethernet interfaces (even with the espressif/arduino-esp32 code) and of course you have WiFi which can have an IP for STA and for AP mode.

So how would those be specified when querying? Also which is the "preferred" interface? What IP-address from which interface would you expect when calling localIP() ?
Let's hope we won't need to keep enumerating over them to finally have one with the desired zone appended to the localIPv6 address.
I think we won't have several globalIPv6 addresses on different interfaces, even though it would be possible from a routing perspective. (probably metrics needed to specify the "costs" for using a specific interface)

[sgryphon]

For IPv4 there isn't really a difference between global and local IP.

Sorry. Maybe you meant "Most local IPv4 addresses are global scope addresses", which is true, but has nothing to do with being local.

Because "Most remote IPv4 addresses are global scope addresses" is also true. So there are a lot of global IPv4 addresses that are not local -- they are remote.

This is just because most IPv4 addresses (either local or remote) are global scope addresses.

Link-local scope IPv4 addresses (169.254.0.0/16) are uncommon to see because the standard says don't assign one if you have DHCP, and if you do have one and receive DHCP then replace it. Unlike IPv6 where you keep (rather than replace) your link-local scope addresses when you get a global scope addresses. By default link-local IPv4 addresses are also disabled in LWIP.

the preferred IP type of your host's IP address (deliberately not calling it local)

But you should call it local here. The word local (by itself) means your host's IP address.

and still functions to get localIPv6 and globalIPv6

This is where the word local (by itself) is being used inconsistently.

Maybe you meant "functions to get link-local scope and global scope IP addresses".

In my screen shot above:

• fe80::2ab8:3926:aff:7ccf/64 scope link is a local host link-local scope address
• 2407:8800:bc61:1340:f949:fb86:d418:aaa4/64 scope globalis a local host global scope address

I.e. an address can be both for the local host and have a global scope.

Current the IPv4 function:

• localIP() means get the IP address of your local host; usually this is a global scope address, e.g. 192.168.1.209. This is the same meaning (local host) where the function name localIP() is used elsewhere

Current the way the IPv6 functions are named:

• localIPv6() is inconsisent. It does not return a local host global scope address like the IPv4 version, but instead returns a local host link-local scope address. I think it should function the same as localIP(), e.g. return 2407:8800:bc61:1340:f949:fb86:d418:aaa4

Using localIP() to get the IPv4 and globalIPv6() to get the equivalent IPv6 makes no sense; they should have the same name.

To be able to get all IPv6 addresses, I propose an index, similar to dnsIP(), so:

• localIP(), on the WiFi interface, returns 192.168.1.209 (global scope).
• localIPv6() (which is the same as localIPv6(0)), on the WiFi interface, returns 2407:8800:bc61:1340:f949:fb86:d418:aaa4 (global scope).
• localIPv6(1), on the WiFi interface, returns fd7c:e25e:67e8:40:f949:fb86:d418:aaa4 (ULA address).
• localIPv6(2), on the WiFi interface, returns fe80::f949:fb86:d418:aaa4 (link-local scope).
• localIPv6(3), and above, returns empty

The order of the above addresses is based the section 2.4 precedence table of RFC 6724.

[sgryphon]

So IMHO localIP() as function name for the generic call to get the preferred IP for this node may even be wrong, just for the simple fact that this might also return a global IPv4 address if the interface doesn't have a local IPv6 (is this even possible?)
After all the preference only differentiates between IPv4 and IPv6.

There is nothing wrong with a local host having a global scope address -- in fact normally this is the case, e.g. my local host has lots of global scope addresses: 192.168.1.209, 2407:8800:bc61:1340:f949:fb86:d418:aaa4, etc.

I'm not comfortable with the word preferred, even if I used it in the past, I didn't mean anything to do with user selected preference. There is a term in RFC 6724 for precedence.

The main purpose for showing a local host address I presume is so it can be display and used by another system as a destination address (another use would be for examining logs). The main criteria here is appropriate scope; in the general case of a global scope connection this means prioritise global scope over link-local scope (both addressess will work fine in the local host network).

I'm happy with the discussion of separate discussions for IPv4 vs IPv6, and will update the suggestion above.