NAME

bindtest —

test bind(2) behavior on IPv6 implementation

SYNOPSIS

bindtest

[

-126APlstv

] [

-b IPv4broadcast

] [

-o IPv4address

] -p port

DESCRIPTION

bindtest tests interaction between IPv4/IPv6 socket interface, implemented into the kernel it has underneath.

RFC2553 defines socket API for IPv6, and relationship between IPv6 wildcard bind(2) socket (::.port) and IPv4 wildcard bind(2) socket (0.0.0.0.port). However, the document does not define ordering constraints between them, relationship with specific bind(2), nor relationship with speficfic bind(2) using IPv4 mapped IPv6 address (::ffff:127.0.0.1).

bindtest tries to reveal the behavior implemented in the kernel, and shows some report to standard output. As RFC2553 does not define the expected behavior, we have no idea what the result should be.

The following command line options are accepted. For details please see the following subsections:

-1: After successful bind(2) on two sockets, try a connect(2) to the first socket. Works only when -t is specified as well.
-2: Like -1, but try a connect(2) to the second socket. Works only when -t is specified as well.
-6: Uses IPV6_V6ONLY socket option on AF_INET6 sockets (note that not many stacks implement this yet).
-A: Set SO_REUSEADDR socket option for all the sockets.
-P: Set SO_REUSEPORT socket option for all the sockets.
-b IPv4broadcast: Specifies an additional broadcast address to test if UDP datagram to IPv4broadcast, which is an IPv4 broadcast address, can be sent on an AF_INET6 socket as an IPv4-mapped IPv6 address. This option can only be specified for UDP. Currently, the -s option and this option cannot coexist.
-l: With TCP test, normally bindtest will issue bind(2) and listen(2) for the first socket, then bind(2) and listen(2) for the second socket. With -l, bindtest will issue two bind(2) first, then two listen(2) system calls. Works only when -t is specified as well.
-o IPv4addresss: Specifies an additional address to test connect(2) or sendto(2) behavior. The address should already be assigned to the node, and should not be the loopback address (127.0.0.1).
-p port: port specifies the TCP/UDP port number used for the test. The port needs to be vacant. The flag is mandatory.
-s: Summary output. See the following subsection for details.
-t: By default bindtest will use SOCK_DGRAM socket for testing. With -t, bindtest will use SOCK_STREAM socket instead.
-v: bindtest prints its version and exits without testing anything.

The test process

The goal of bindtest is to detect how the implementation interpteted and coded RFC2553. More specifically, the following items are tested:

If we issue two bind(2) system calls to two sockets with the same port number, will it go successful, or either of/both of them fails?
For the failure case, does the ordering of bind(2) matter?
If the two bind(2) attemps go successful, which socket will get incoming traffic?
For TCP case, does the order between bind(2) and listen(2) affect the behavior?

The list of addresses to be tested with bind(2) are as below:

wildcard: :: and 0.0.0.0
loopback: ::1 and 127.0.0.1
IPv4 mapped wildcard and loopback:: ::ffff:0.0.0.0 and ::ffff:127.0.0.1
invalid address:: ::ffff:0.0.0.1 and 0.0.0.1. Their goal is to test common programming mistakes in the implementation.

When two sockets become ready after bind(2), bindtest attempts to send some packets to see which socket accepts which packets. For UDP cases, it tries to issue sendto(2) for each address bound to each socket, and for the additional address if specified by the -o option. For TCP cases, the program tries to issue connect(2) for one destination specified by the -1, -2, or -o IPv4address options. -1 and -2 let bindtest connect(2) to the address that the program has used for bind(2). With -o, bindtest connects to the address specified by the extra argument, IPv4address. Note that the options -1 and -2 are meaningful only when -t is specified.

When the -o IPv4address option is specified, the address can be any valid IPv4 address in theory, but, for the testing purpose, the address is meaningful only when it is an IPv4 address assigned on the testing node itself.

The -l option is meaningful only when the corresponding socket is TCP. It specifies bindtest to issue bind(2) for both two sockets first, and then to issue listen(2) for the sockets. Normally, the program calls the two calls for the first socket, and then calls them for the second socket. This option exists because there is an operating system that behaves differently for those two cases.

Summary output

With -s, bindtest generates summarized output instead of verbose output. Here is a sample output, and the legends for summarized output.

starting tests, socktype = SOCK_DGRAM, SO_REUSEADDR, V6ONLY
wild4 wild6 loop4 loop6 wildm loopm onem one4 wild4: x o[--1x] o[-21x] o[-21x] ?2(49) ?2(49) ?2(49) ?2(49) wild6: o[--2x] x o[-20x] o[-20x] ?2(49) ?2(49) ?2(49) ?2(49) loop4: o[1-2x] o[1-0x] x o[120x] ?2(49) ?2(49) ?2(49) ?2(49) loop6: o[1-2x] o[1-0x] o[120x] x ?2(49) ?2(49) ?2(49) ?2(49) wildm: ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) loopm: ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) onem: ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) one4: ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49) ?1(49)

bindtest will make a two set of socket(2) and bind(2). The first set is presented on the lefthand side. The second set is presented above the table.

o

The second bind(2) attempt was successful after the first bind(2). “o” is followed by three letters enclosed in square brackets. The first letter shows the test result after sendto(2) to the first socket address (listed on the topmost row). The second letter shows the test result after sendto(2) to the second socket address (listed on the leftmost column). The third letter shows the test result after sendto(2) to the IPv4 additional address, when specified by the -o option, through an AF_INET socket. The fourth letter shows the test result after sendto(2) to the additional IPv4 address, when specified by the -o option, through an AF_INET6 socket using IPv4-mapped IPv6 address.

-: The address is wildcard (:: or 0.0.0.0) and no attempts were made to test send/recv behavior.
0: None of the sockets received the packet.
1: The first socket received the packet.
2: The second socket received the packet.
b: Both sockets received the packet. This result is not supposed to happen, but exists just in case.
x: The attempt of sendto(2) failed. UDP cases only.
c: The attempt of connect(2) failed. TCP cases only.

The meaning of the result table is the same for TCP cases, whereas only one of the three possible cases should be tried in a single execution of the test.

x

bind(2) failed for the second set, with EADDRINUSE.

!1

socket(2) failed for the first set. Normally you will not see this, unless you run bindtest on IPv4-only/IPv6-only kernel. Will be followed by errno(2) in paren.

!2

socket(2) failed for the second set. Normally you will not see this, unless you run bindtest on IPv4-only/IPv6-only kernel. Will be followed by errno(2) in paren.

?1

bind(2) failed for the first set. Will be followed by errno(2) in paren.

?2

bind(2) failed for the second set, with some error other than EADDRINUSE. Will be followed by errno(2) in paren.

RETURN VALUES

bindtest exits with 0 on success, and non-zero on errors.

HISTORY

The bindtest command first appeared in WIDE/KAME IPv6 protocol stack kit.