Document more prominently that net: :inet6 means IPv6 + IPv4 on Linux by default #120

I was recently debugging some deployments in containers which lead to interesting interactions of various network stacks and forwarded ports. One of the issues was IPv6, net: :inet6, and its impact on IPv4 operations.

One of the use-cases I worked with lead to

    children = [
      Supervisor.child_spec({Plug.Cowboy, scheme: :http, plug: HelloWorld.Plug, options: [net: :inet, ip: {0,0,0,0}, port: port, ref: "localhost4"]},
        id: "localhost4"),
      Supervisor.child_spec({Plug.Cowboy, scheme: :http, plug: HelloWorld.Plug, options: [net: :inet6, ip: {0,0,0,0,0,0,0,0}, port: port, ref: "localhost6"]},
        id: "localhost6")
    ]

This is of course a minimized reproducer setup, in real-life the IP addresses came from configuration edited by the admin.

This caused

15:06:57.714 [error] Failed to start Ranch listener "localhost6" in :ranch_tcp:listen(%{
  num_acceptors: 100,
  socket_opts: [
    :inet6,
    {:ip,
     {0,
      0,
      0,
      0,
      0,
      0,
      0,
      0}},
    {:port,
     8080}
  ],
  max_connections: 16384
}) for reason :eaddrinuse (address already in use)

It took me a while to realize that

    children = [
      {Plug.Cowboy, scheme: :http, plug: HelloWorld.Plug, options: [net: :inet6, port: port]}
    ]

makes the application listen on both IPv6 and IPv4, at least by default on recent Linuxes, driven by the default sysctl value

net.ipv6.bindv6only = 0

The https://plug-cowboy.hexdocs.pm/Plug.Cowboy.html documentation says

For example, you can set :ipv6_v6only to true if you want to bind only on IPv6 addresses.

but that note is only below the list of options, of which the first one is

• :net - if using :inet (IPv4 only, the default) or :inet6 (IPv6).

Would it make sense to expand that :inet6 documentation to something like

... or :inet6 (IPv6, which on Linux also includes IPv4 by default).

or

... or :inet6 (IPv6, see below when it also means IPv4).

and have some longer section about Linux, net.ipv6.bindv6only = 0, :ipv6_v6only, and their interactions?

People might be happy to learn that they don't need to create two children to listen on both address families and fiddle with ref and id ... and on the other hand in case they get inputs like 0.0.0.0 + :: from their admin, make sense from the error message more easily.