-
-
Notifications
You must be signed in to change notification settings - Fork 30
/
Copy pathmcjoin.1
216 lines (216 loc) · 6.54 KB
/
mcjoin.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
.\" Hey Emacs, this is an -*- nroff -*- document
.\"
.\" Copyright (C) 2008-2021 Joachim Wiberg
.\"
.\" 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 THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR 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.
.\"
.Dd January 14, 2021
.Dt MCJOIN 1
.Os
.Sh NAME
.Nm mcjoin
.Nd tiny multicast testing tool
.Sh SYNOPSIS
.Nm
.Op Fl dhjosv
.Op Fl b Ar BYTES
.Op Fl c Ar COUNT
.Op Fl f Ar MSEC
.Op Fl i Ar IFNAME
.Op Fl l Ar LEVEL
.Op Fl p Ar PORT
.Op Fl t Ar TTL
.Op Fl w Ar SEC
.Op Fl W Ar SEC
.Op Ar [SOURCE,]GROUP0[:PORT] .. [SOURCE,]GROUPN[:PORT] | [SOURCE,]GROUP[:PORT]+NUM
.Sh DESCRIPTION
.Nm
can be used to join IPv4 and IPv6 multicast groups, display progress as
multicast packets are received, or sent when acting as sender, and also
send multicast packets on select groups.
.Pp
.Bd -ragged -offset center
.Sy Note:
an IPv6 group with custom port must be written as
.Ar [ADDR]:port ,
i.e., with enclosing brackets.
.Ed
.Pp
.Nm
can help verify intended IGMP snooping functionality in layer-2 bridges
(switches), as well as verify forwarding of multicast in static
.Nm ( SMCRoute )
or dynamic
.Nm ( mrouted ,
.Nm pimd ,
.Nm pimd-dense ,
or
.Nm pim6sd )
multicast routing setups.
.Pp
.Nm
supports source-specific multicast, SSM (S,G), as well as any-source
multicast, ASM (*,G). The source IP of an (S,G) pair is an optional
argument that must precede the group and be separated with a comma. No
spaces are allowed between source and group in this form. Multiple
(S,G) pairs are separated with space.
.Pp
.Nm
does not create or send IGMP or MLD frames directly. It only asks the
underlying UNIX kernel for groups from a specific interface, which is
then converted to the appropriate wire format by the kernel. This
means, for instance, that if you want to create an IGMP v3 membership
report on the wire that joins one group from multiple sources, you tell
.Nm
to join two (S,G) pairs. The conversion to IGMP v3 report format is
done by the kernel.
.Pp
On Linux systems you can change the IGMP version of an interface, and
thus what type of packets the kernel generates, by writing to the file
.Pa /proc/sys/net/ipv4/conf/eth0/force_igmp_version .
E.g., to change
.Cm eth0
to IGMPv2:
.Bd -literal -offset indent
echo 2 | sudo tee /proc/sys/net/ipv4/conf/eth0/force_igmp_version
.Ed
.Sh OPTIONS
With no options given
.Nm
acts as a multicast receiver (or sink), joining the default group
225.1.2.3, listening on the default interface, eth0, binding to the
default port, 1234.
.Pp
Use the following options to adjust this behavior:
.Bl -tag -width Ds
.It Fl b Ar BYTES
Payload in bytes over IP/UDP header (42 bytes), default: 100
.It Fl c Ar COUNT
Stop sending/receiving after COUNT number of packets
.It Fl d
Run as a daemon in the background, detached from the current terminal.
All output, except progress is sent to
.Xr syslog 3
.It Fl f Ar MSEC
Frequency, poll/send every MSEC milliseconds, default: 100
.It Fl h
Print a summary of the options and exit
.It Fl i Ar IFNAME
Interface to use for sending/receiving multicast, default: eth0
.It Fl j
Join groups, default unless acting as sender
.It Fl l Ar LEVEL
Control
.Nm
log level; none, notice, debug. Default: notice
.It Fl o
Old (plain/ordinary/original) output, no fancy progress bars
.It Fl p Ar PORT
UDP port number to send/listen to, default: 1234
.It Fl s
Act as sender, sends packets to select groups, 1/100 msec, default: no
.It Fl t Ar TTL
TTL to use when sending multicast packets, default: 1
.It Fl v
Show version information
.It Fl w Ar SEC
Initial wait, sleep
.Ar SEC
seconds before starting anything. Useful for scripting test systems
that launch
.Nm
at boot without syncing with networking bring-up
.It Fl W Ar SEC
Timeout, in seconds, before
.Nm
exits, regardless of how many packets have been received. With this
option
.Nm
exit either after
.Ar SEC
seconds, or after
.Ar COUNT
packets have been received
.El
.Sh USAGE
To verify multicast connectivity, the simplest way is to run
.Nm
on one system, without arguments, and on the other with the command
option
.Ar -s .
In this setup one system joins the group
.Ar 225.1.2.3
waiting for packets to arrive, and the other end starts sending packets
to the same group. To verify routing of multicast, make sure to add the
.Fl t Ar TTL
option to the sender since the default TTL is 1 and every router
(simplified) decrements the TTL.
.Pp
For a more advanced example, say you want to verify that your topology
can forward 20 consecutive groups in the MCAST_TEST_NET, as defined in
RFC5771. Simply add the following as a standalone argument to both the
receiver and the sender:
.Ar 233.252.0.1+20
.Pp
For non-consecutive groups, simply add them in any order you want, up to
250 groups are supported:
.Ar 225.1.2.3 226.3.2.1+12 225.3.2.42 232.43.211.234
.Pp
To run
.Nm
as both a sender and a receiver on the same host you will likely need to
employ something like network namespaces (Linux netns) for at least one
of them. Otherwise the network stack will likely let the sender's data
stream take a short cut to the receiver, without passing through an
actual wire.
.Pp
Also, like most network applications, to run properly
.Nm
needs both the loopback (lo) interface and a default route set up. At
least in the default (receiver) case. In a network namespace neither of
these are set up by default.
.Sh INTERACTIVE
.Nm
can be controlled at runtime with the following keys:
.Pp
.Bl -tag -width Ctrl-L -compact -offset indent
.It Cm d
Toggle frame duplication
.It Cm h
Toggle help text
.It Cm l
Toggle debug log
.It Cm q
Quit mcjoin
.It Cm t
Toggle viewing modes
.It Cm PgUp
Scroll log view up
.It Cm PgDn
Scroll log view down
.It Cm Ctrl-L
Refresh display
.It Cm Ctrl-C
Quit mcjoin
.El
.Sh SEE ALSO
.Xr ping 1 ,
.Xr mgen 1 ,
.Xr nemesis 1
.Sh BUGS
Use the project's GitHub page to file bug reports, feature requests or
patches (preferably as GitHub pull requests), or questions at
.Aq https://github.com/troglobit/mcjoin
.Sh AUTHORS
Originally based on an example by David Stevens, further developed and
maintained by Joachim Wiberg at GitHub.