.\" Copyright (c) 2010-2011, Red Hat, Inc.

.\"

.\" Permission to use, copy, modify, and/or distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

.\" copyright notice and this permission notice appear in all copies.

.\"

.\" THE SOFTWARE IS PROVIDED "AS IS" AND RED HAT, INC. DISCLAIMS ALL WARRANTIES

.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES

.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL RED HAT, INC. BE LIABLE

.\" FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION

.\" OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN

.\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

.\"

.\" Author: Jan Friesse <jfriesse@redhat.com>

.\"

.Dd Jun 22, 2011

.Dt OMPING 8

.Os

.

.Sh NAME

.Nm omping

.Nd test IP multicast

.Sh SYNOPSIS

.Nm

.Op Fl 46CDEFqVv

.Op Fl c Ar count

.Op Fl i Ar interval

.Op Fl M Ar transport_method

.Op Fl m Ar mcast_addr

.Op Fl O Ar op_mode

.Op Fl p Ar port

.Op Fl R Ar rcvbuf

.Op Fl r Ar rate_limit

.Op Fl S Ar sndbuf

.Op Fl T Ar timeout

.Op Fl t Ar ttl

.Op Fl w Ar wait_time

.Ar remote_addr...

.Sh DESCRIPTION

The

.Nm

is program which uses User Datagram Protocol to determine if computer is able to send

and/or receive IP unicast and multicast or Broadcast packets from the network. It's designed to be

used in very similar way as

.Xr ping 8

and also has some features of the

.Xr fping 8

command.

Where

.Xr ping 8

and

.Nm

differ is in who replies. In

.Xr ping 8

replies are sent by the operating system and with

.Nm

another instance of

.Nm

sends the reply. This mean that

.Nm

must be running on all computers to test sending/receiving IP multicast/broadcast.

Its arguments are as follows:

.Bl -tag -width Ds

.It Fl 4

Force usage of IPv4.

.It Fl 6

Force usage of IPv6.

.It Fl C

Display continuous statistics for every reply message.

.It Fl D

Disable packet duplicate detection. Option is default for interval 0.

.It Fl E

Default behaviour when every client is in stop state is to exit. This may happen if all server sends

stop message or if

.Ar count

query messages was sent. This option changes default behaviour and

.Nm

doesn't quit automatically.

.It Fl F

Allow entering of arguments which are not allowed or not recommended by the specification. This is

typically the interval parameter. This option may be used multiple times.

.It Fl q

Quiet output. Nothing is displayed except state changes and summary. Option can be used twice and

then only summary is displayed.

.It Fl V

Display version and quit. Option can be used twice and then remote version is displayed.

.It Fl v

Set level of verbosity. Parameter can be used multiple times to achieve higher verbosity.

.It Fl c Ar count

Number of request packets to send to each target. After sending

.Ar count

query messages, given client is put to stop state and it is no longer sending query

messages.

.It Fl i Ar interval

Wait

.Ar interval

seconds between sending each request packet. Float values are supported in millisecond precision.

It's possible to set there 0 with meaning that packets are sent ether after previous unicast reply

is received or after 1 millisecond, depending on which of these intervals is smaller. The default

is to wait for one second between each packet.

.It Fl M Ar transport_method

Set transport method to use. This can be

.Cm asm

for Any-source Multicast,

.Cm ssm

for Source-specific Multicast and

.Cm ipbc

for IP Broadcast.

.It Fl m Ar mcast_addr

Multicast or broadcast address to listen on for multicast/broadcast answer messages.

Default is 232.43.211.234 for IPv4 and ff3e::4321:1234 for IPv6 multicast, or broadcast address of

local interface for Broadcast.

.It Fl O Ar op_mode

.Nm

can be running in three different modes. Default and recommended mode for quick testing is

.Cm normal

mode, when

.Nm

behaves like client and server together. It sends queries and is able to respond them.

.\"

.\" Temporarily disabled

.\"

.\" In

.\" .Cm server

.\" mode

.\" .Nm

.\" never sends it's own queries but responds to other nodes one.

Finally the

.Cm client

mode sends queries, but never respond to other nodes.

.It Fl p Ar port

Port to bind and listen on for both unicast and multicast/broadcast messages. Default is 4321.

.It Fl R Ar rcvbuf

Set socket rcvbuf. Minimum value for this option is 2048. If not specified, rcvbuf is not changed

and default OS provided value is used.

.It Fl r Ar rate_limit

Rate limit interval between two query messages to

.Ar rate_limit

seconds. Default value is same as

.Ar interval

given by

.Fl i

option. Rate limiting can be disabled by specifying 0 as value. Rate limiting is by default disabled

for

.Fl i

with 0 seconds.

.It Fl S Ar sndbuf

Set socket sndbuf. Minimum value for this option is 2048. If not specified, sndbuf is not changed

and default OS provided value is used.

.It Fl T Ar timeout

Specify a timeout, in seconds, before

.Nm

exits regardless of how many packets have

been received.

.It Fl t Ar ttl

Time-To-Live of sent packets.

.It Fl w Ar wait_time

after

.Nm

is stopped (by sending SIGINT or timeout expire) it is moved to special state when no queries are

made and server answer all queries by server response (stop message). This makes possible to give

correct (unbiased) result of lost packets on other nodes. Default is 3 times interval or 1 second,

depending which one is larger. Also special value 0 can be used to not wait at all or -1 which

means wait forever (this can be still terminated by sending SIGINT).

.It Ar remote_addr

List of addresses to test. One of them must be address of local internet interface. This

local address is used for bind and listening on for unicast packets. It's also used to determine

which interface should be used for sending multicast/broadcast replies.

.El

.Pp

Program is normally terminated by SIGINT. After signal receive summary is displayed. You can also

display summary during running by sending SIGINFO or SIGUSR1 signal.

.Pp

When using

.Nm

for fault isolation, it should first be run against local internet

interface only, to verify that the local network interface is up and running, and firewall

is correctly configured. This mode is available by entering only local IP address.

.Sh EXIT STATUS

.Ex -std

.Sh EXAMPLES

The following commands and output is a typical way how to find-out and solve network problems

using omping. In this situation, we have 3 computers named node-01, node-02 and node-03 with IP

addresses 192.168.1.101 - 192.168.1.103. Let's run the following command on all of them.

.Pp

.Dl $ omping node-01 node-02 node-03

.Pp

on all of nodes we should be able to seen similar output

.Pp

.Dl node-01 : waiting for response msg

.Dl node-03 : waiting for response msg

.Dl node-01 : joined (S,G) = (*, 232.43.211.234), pinging

.Dl node-03 : joined (S,G) = (*, 232.43.211.234), pinging

.Dl node-01 :   unicast, seq=1, size=69 bytes, dist=0, time=0.192ms

.Dl node-01 : multicast, seq=1, size=69 bytes, dist=0, time=0.284ms

.Dl node-03 :   unicast, seq=1, size=69 bytes, dist=0, time=0.279ms

.Dl node-03 : multicast, seq=1, size=69 bytes, dist=0, time=0.360ms

.Pp

The first two lines tell us, that node-02 (actual node) is waiting for a response

message from node-01 and node-03. The second two lines contain information, that

we were successfully able to send an init message and also received a response

message from remote nodes. Both of these messages are unicast, so we are able to

send and receive unicast messages on a given port. If all of nodes are up and

.Nm

is running on all of them, but we are not able to receive a response

message, it's time to check connectivity between nodes. First make sure that

you are able to

.Xr ping 8

them. If so, make sure that your firewall allows port 4321 to receive udp packets.

.Pp

The next line tells us that we were able to receive a 69 byte unicast response message from

node-01, with a sequence number of 1. The distance between the computers is 0 so they are on

the same link net. Time between send and receive packet was 0.192 ms, that is also the

current average time and lastly there were no lost packets.

.Pp

The 6th line tells us the same information as the previous one, but the received message

is a multicast message. It means, that multicast is probably well configured.

.Pp

The 7th and 8th lines are same as previous two one but for node-03.

.Pp

If the node is able to receive unicast packets, but never multicast, it means that multicast

configuration is incorrect. It's recommended to turn off your firewall. If multicast packets start

to arrive, great. If not, the problem is hidden in the switches/routers between the nodes. Contact

your system administrator to allow multicast traffic on the switch or router.

.Pp

.Nm

is terminated by SIGINT signal (CTRL-c). Summary statistics are shown

.Pp

.Dl node-01 :   unicast, xmt/rcv/%loss = 18/18/0%, min/avg/max/std-dev = 0.177/0.301/0.463/0.073

.Dl node-01 : multicast, xmt/rcv/%loss = 18/18/0%, min/avg/max/std-dev = 0.193/0.335/0.547/0.090

.Dl node-03 :   unicast, xmt/rcv/%loss = 21/21/0%, min/avg/max/std-dev = 0.272/0.299/0.327/0.017

.Dl node-03 : multicast, xmt/rcv/%loss = 21/20/4% (seq>=2 0%), min/avg/max/std-dev = 0.347/0.388/0.575/0.055

.Pp

Last line has additional information (seq>=2 %0) which means, that after receiving first multicast

packet with seq number 2, no other multicast packet was lost. Because creating multicast tree is

time consuming, it's pretty normal to lost first few multicast packets. rcv field can also be

formatted like

.Pp

.Dl node-01 :   unicast, xmt/rcv/%loss = 3/3+1/0%, min/avg/max/std-dev = 0.294/0.299/0.305/0.006

.Pp

This means, that 1 duplicate packet was received. It's possible to find out duplicate packet by

looking to output and find line which has following format

.Pp

.Dl node-01 :   unicast, seq=2 (dup), size=69 bytes, dist=0, time=0.469ms

.Sh SEE ALSO

.Xr fping 8 ,

.Xr ping 8

.Sh STANDARDS

.Nm

uses Internet-Draft draft-ietf-mboned-ssmping-08 as underlaying protocol and tries

to be as compliant as possible.

.Sh AUTHORS

The

.Nm

utility was written by

.An Jan Friesse Aq jfriesse@redhat.com .

.Sh BUGS

.Bl -dash

.It

Some OSes may not have support for receiving TTL from packet.

.Nm

then cannot provide distance information.

.It

Some OSes may not provide information about packet receive. Less precise actual time is then used.

.It

.Nm

highly depends on precise

.Xr poll 2

and

.Xr gettimeofday 3

functions. If OS doesn't provide at least milliseconds precision, results may be incorrect.

.El