BINDTEST(1) BSD General Commands Manual BINDTEST(1)NAMEbindtest — test bind(2) behavior on IPv6 implementation
SYNOPSISbindtest [-126APlstv] [-b IPv4broadcast] [-o IPv4address] -p port
DESCRIPTIONbindtest tests interaction between IPv4/IPv6 socket interface, imple‐
mented into the kernel it has underneath.
RFC2553 defines socket API for IPv6, and relationship between IPv6 wild‐
card bind(2) socket (::.port) and IPv4 wildcard bind(2) socket
(0.0.0.0.port). However, the document does not define ordering con‐
straints between them, relationship with specific bind(2), nor relation‐
ship 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.
-vbindtest 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 pro‐
gramming 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 bindtestconnect(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 speci‐
fied by the -o option, through an AF_INET socket. The fourth let‐
ter 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 sup‐
posed 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 VALUESbindtest exits with 0 on success, and non-zero on errors.
SEE ALSO
R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
Extensions for IPv6, RFC2553, March 1999.
bind(2), tcpdump(8)HISTORY
The bindtest command first appeared in WIDE/KAME IPv6 protocol stack kit.
KAME June 25, 2001 KAME
