From d06331382862c32fb9606887aeccd67e5c209f99 Mon Sep 17 00:00:00 2001 From: Sektor van Skijlen Date: Mon, 7 Aug 2023 17:23:53 +0200 Subject: [PATCH] [docs] Updating the explicit information for binding to IPv6 wildcard (#2765). --- docs/API/API-functions.md | 8 ++++++-- docs/API/API-socket-options.md | 20 ++++++++++++++++---- docs/apps/srt-live-transmit.md | 17 +++++++++-------- 3 files changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/API/API-functions.md b/docs/API/API-functions.md index 042ece34c..f897ffcc2 100644 --- a/docs/API/API-functions.md +++ b/docs/API/API-functions.md @@ -359,8 +359,12 @@ int srt_bind(SRTSOCKET u, const struct sockaddr* name, int namelen); Binds a socket to a local address and port. Binding specifies the local network interface and the UDP port number to be used for the socket. When the local address is a wildcard (`INADDR_ANY` for IPv4 or `in6addr_any` for IPv6), then -it's bound to all interfaces (although see `SRTO_IPV6ONLY` and additional -information below for details about the wildcard address in IPv6). +it's bound to all interfaces. + +**IMPORTANT**: When you bind an IPv6 wildcard address, note that the +`SRTO_IPV6ONLY` option must be set on the socket explicitly to 1 or 0 prior to +calling this function. See +[`SRTO_IPV6ONLY`](API-socket-options.md#SRTO_IPV6ONLY) for more details. Binding is necessary for every socket to be used for communication. If the socket is to be used to initiate a connection to a listener socket, which can be done, diff --git a/docs/API/API-socket-options.md b/docs/API/API-socket-options.md index 10e732b0b..df4772d55 100644 --- a/docs/API/API-socket-options.md +++ b/docs/API/API-socket-options.md @@ -647,10 +647,22 @@ and the actual value for connected sockets. Set system socket option level `IPPROTO_IPV6` named `IPV6_V6ONLY`. This is meaningful only when the socket is going to be bound to the IPv6 wildcard address `in6addr_any` -(known also as `::`). In this case this option must be also set explicitly to 0 or 1 -before binding, otherwise binding will fail (this is because it is not possible to -determine the default value of this above-mentioned system option in any portable or -reliable way). Possible values are: +(known also as `::`). If you bind to a wildcard address, you have the following +possibilities: + +* IPv4 only: bind to an IPv4 wildcard address +* IPv6 only: bind to an IPv6 wildcard address and set this option to 1 +* IPv4 and IPv6: bind to an IPv6 wildcard address and set this option to 0 + +This option's default value is -1 because it is not possible to determine the default +value on the current platform, and if you bind to an IPv6 wildcard address, this value +is required prior to binding. When you bind implicitly by calling `srt_connect` on the +socket, this isn't a problem -- binding will be done using the system-default value and then +extracted afterwards. But if you want to bind explicitly using `srt_bind`, this +option must be set explicitly to 0 or 1 because this information is vital for +determining any potential bind conflicts with other sockets. + +Possible values are: * -1: (default) use system-default value (can be used when not binding to IPv6 wildcard `::`) * 0: The binding to `in6addr_any` will bind to both IPv6 and IPv4 wildcard address diff --git a/docs/apps/srt-live-transmit.md b/docs/apps/srt-live-transmit.md index cc8a25e22..f29e1ed7a 100644 --- a/docs/apps/srt-live-transmit.md +++ b/docs/apps/srt-live-transmit.md @@ -285,11 +285,13 @@ specify the host as `::`. NOTE: Don't use square brackets syntax in the **adapter** parameter specification, as in this case only the host is expected. -3. If you want to listen for connections from both IPv4 and IPv6, mind the -`ipv6only` option. The default value for this option is system default (see -system manual for `IPV6_V6ONLY` socket option); if unsure, you might want to -enforce `ipv6only=0` in order to be able to accept both IPv4 and IPv6 -connections by the same listener, or set `ipv6only=1` to accept exclusively IPv6. +3. If you bind to an IPv6 wildcard address (with listener mode, or when using the `bind` +option), setting the `ipv6only` option to 0 or 1 is obligatory, as it is a part +of the binding definition. If you set it to 1, the binding will apply only to +IPv6 local addresses, and if you set it to 0, it will apply to both IPv4 and +IPv6 local addresses. See the +[`SRTO_IPV6ONLY`](../API/API-socket-options.md#SRTO_IPV6ONLY) option +description for details. 4. In rendezvous mode you may only interconnect both parties using IPv4, or both using IPv6. Unlike listener mode, if you want to leave the socket @@ -303,9 +305,8 @@ Examples: * `srt://[::]:5000` defines caller mode (!) with IPv6. -* `srt://[::]:5000?mode=listener` defines listener mode with IPv6. If the - default value for `IPV6_V6ONLY` system socket option is 0, it will accept - also IPv4 connections. +* `srt://[::]:5000?mode=listener&ipv6only=1` defines listener mode with IPv6. + Only connections from IPv6 callers will be accepted. * `srt://192.168.0.5:5000?mode=rendezvous` will make a rendezvous connection with local address `INADDR_ANY` (IPv4) and port 5000 to a destination with