File: smcroute.8

package info (click to toggle)
smcroute 2.4.4-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 936 kB
  • sloc: ansic: 4,249; sh: 1,351; perl: 169; makefile: 99
file content (564 lines) | stat: -rw-r--r-- 18,914 bytes parent folder | download
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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
.Dd $Mdocdate: May 6 2017 $
.Dt SMCROUTE 8 SMM
.Os
.Sh NAME
.Nm smcroute
.Nd SMCRoute, a static multicast router
.Sh SYNOPSIS
.Nm smcrouted
.Op Fl nNhsv
.Op Fl c Ar SEC
.Op Fl d Ar SEC
.Op Fl e Ar CMD
.Op Fl f Ar FILE
.Op Fl I Ar NAME
.Op Fl l Ar LVL
.Op Fl p Ar USER:GROUP
.Op Fl P Ar FILE
.Op Fl t Ar ID
.Nm smcroutectl
.Op Fl dtv
.Op Fl I Ar NAME
.Op Ar COMMAND
.Pp
.Nm smcroutectl
.Ao help | flush | kill | restart | version Ac
.Nm smcroutectl
.Ao show Ac
.Op groups | routes
.Nm smcroutectl
.Ao add \ | \ \ rem Ac Ao IFNAME Ac Oo SOURCE Oc Ar GROUP[/LEN] IFNAME Op IFNAME ...
.Nm smcroutectl
.Ao join | leave Ac Ao IFNAME Ac Oo SOURCE Oc Ar GROUP
.Sh DESCRIPTION
.Nm
is both a daemon and command line tool to manipulate the multicast
routing table of a UNIX kernel.  It supports both IPv4 and IPv6
multicast routing.
.Nm
can be used as an alternative to dynamic multicast routers like
.Nm mrouted
or
.Nm pimd
in situations where static multicast routes should be maintained and/or
no proper IGMP or MLD signaling exists.
.Pp
Multicast routes exist in the UNIX kernel as long as a multicast routing
daemon is running.  On Linux, multiple multicast routers can be used
simultaneously with different multicast routing tables.  To run
.Nm smcrouted
and,
.Nm mrouted
at the same time, set the former to use a routing table other than the
default (0).
.Pp
.Nm smcrouted
modifies the kernel routing table and needs either full
.Ar superuser rights ,
or
.Cm CAP_NET_ADMIN
on Linux.  This also applies to
.Nm smcroutectl .
.Ss WARNING
Be careful when creating multicast routes.  You can easily flood your
networks by inadvertently creating routing loops.  Either direct loops
listing an inbound interface also as an outbound, or indirect loops by
going through other routers.
.Sh OPTIONS
The following
.Nm smcrouted
commands are available:
.Bl -tag -width Ds
.It Fl n
Run daemon in foreground, do not detach from controlling terminal
.It Fl N
By default
.Nm smcrouted
enables multicast routing on all available, and multicast capable,
interfaces in the system.  These interfaces are enumerated as VIFs,
virtual interfaces, of which most UNIX systems have a very limited
amount, usually 32.  This daemon option inverts the behavior so no
interfaces are enabled by default.  Useful on systems with many
interfaces, where multicast routing only makes use of a few.
.Pp
The config file setting
.Ar phyint IFNAME enable
is required to enable the required interfaces.
.It Fl f Ar FILE
Alternate configuration file, default
.Pa /etc/smcroute.conf
.It Fl c Ar SEC
Flush unused dynamic (*,G) multicast routes every
.Ar SEC
seconds.
.Pp
This option is intended for systems with topology changes, i.e., when
inbound multicast may change both interface and source IP address.
E.g. in a setup with at least two VRRP routers.  If there is no way of
detecting such a topology change this option makes sure to periodically
flush all dynamically learned multicast routes so that traffic may
resume.  Flushing of a specific route only occurs if it was unused
during the last flush interval, i.e. there was no traffic matching it.
This avoids toggling between different inbound interfaces if traffic
arrives on several interfaces simultaneously.  In this case, the first
selected inbound interface is retained until traffic on it ceases.
.Pp
Default is 60 sec, set to 0 to disable.  See also the
.Nm smcroutectl Ar flush
command, which can be called manually on topology changes.
.It Fl d Ar SEC
Daemon startup delay.  Delays the probe of interfaces and parsing of the
configuration file.  Note, the PID file is also not created, since the
daemon is not ready yet.
.Pp
This command line option, although useful in some use-cases, is fragile.
It is almost always better to rely on an init or process supervisor that
handles dependencies properly, like
.Xr finit 8 ,
which can wait for interfaces to come up and files to be created before
starting a service.
.It Fl e Ar CMD
Specify external script or command to be called when
.Nm smcrouted
has loaded/reloaded all static multicast routes from the configuration
file, or when a source-less (ANY) rule has been installed.
.It Fl I Ar NAME
Set daemon identity.  Used to create unique PID, IPC socket, and
configuration file names, as well as set the syslog identity.  E.g.,
.Fl I Ar foo
would make
.Nm smcrouted
look for
.Cm /etc/foo.conf ,
write its PID to
.Cm /var/run/foo.pid
and create an IPC socket for
.Cm smcroutectl
in
.Cm /var/run/foo.sock .
.Pp
For
.Nm smcroutectl
the same option can be used to select the proper
.Nm smcrouted
instance to send IPC to.
.Pp
This option is required for both daemon and client when running multiple
.Nm smcrouted
instances, using multiple routing tables, on Linux.
.It Fl l Ar LEVEL
Set log level: none, err, notice, info, debug.  Default is notice.
.It Fl p Ar USER Op :GROUP
Drop root privileges to USER:GROUP after start and retain CAP_NET_ADMIN
capabilities only.  The :GROUP is optional.  This option is only
available when
.Nm smcrouted
is built with libcap support.
.It Fl P Ar FILE
Set PID file name, and optionally full path, in case you need to
override the default identity, or the identity set with
.Fl I Ar NAME .
Regardless, setting this option overrides all others, but it is
recommended to use the ident option instead.
.It Fl s
Let daemon log to syslog, default unless running in foreground.
.It Fl t Ar ID
Set multicast routing table ID.  Remember to also create routing rules
directing packets to the table.  This example uses routing table ID 123:
.Bd -unfilled -offset left
ip mrule add iif eth0 lookup 123
ip mrule add oif eth0 lookup 123
.Ed
.Pp
.Nm Note:
Only available on Linux.
.It Fl v
Show program version.
.El
.Pp
The
.Fl e Ar CMD
option is useful if you want to trigger other processes to start when
.Nm smcrouted
has completed installing dynamic multicast routes from (*,G) rules in
.Pa /etc/smcroute.conf ,
or when a source-less (ANY) route, a.k.a (*,G) multicast rule, from
.Pa /etc/smcroute.conf .
is matched and installed.  For instance, calling
.Ar conntrack
on Linux to flush firewall connection tracking when NAT:ing multicast.
.Pp
The script
.Ar CMD
is called with an argument
.Ar reload
or
.Ar install
to let the script know if it is called on SIGHUP/startup, or when a
(*,G) rule is matched and installed.  In the latter case
.Nm smcrouted
also sets two environment variables:
.Nm source ,
and
.Nm group .
Beware that these environment variables are unconditionally overwritten by
.Nm smcrouted
and can thus not be used to pass information to the script from outside of
.Nm smcrouted .
.Sh COMMANDS
The
.Ar IFNAME
argument in the below
.Nm smcroutectl
commands is the interface name, or an interface wildcard of the form
.Ar eth+ ,
which matches
.Ar eth0 , eth10 ,
etc.  Wildcards are available for inbound interfaces.  The following
commands are available:
.Bl -tag -width Ds
.It Nm add Ar IFNAME [SOURCE] GROUP[/LEN] OUTIFNAME [OUTIFNAME ...]
Add a multicast route to the kernel routing cache so that multicast packets
received on the network interface
.Ar IFNAME
originating from the IP address
.Ar SOURCE
and sent to the multicast group address
.Ar GROUP
will be forwarded to the outbound network interfaces
.Ar OUTIFNAME [OUTIFNAME ...] .
The interfaces provided as
.Ar INIFNAME
and
.Ar OUTIFNAME
can be any multicast capable network interface as listed by 'ifconfig'
or 'ip link list' (incl. tunnel interfaces), including loopback.
.Pp
To add a (*,G) route, either leave
.Ar SOURCE
out completely or set it to
.Ar 0.0.0.0 ,
and if you want to specify a range, set
.Ar GROUP/LEN ,
e.g.
.Ar 225.0.0.0/24 .
.It Nm remove Ar IFNAME [SOURCE] GROUP
Remove a kernel multicast route.
.It Nm flush
Flush dynamic (*,G) multicast routes now.  Similar to how
.Fl c Ar SEC
works in the daemon, this client command initiates an immediate flush of
all dynamically set (*,G) routes.  Useful when a topology change has
been detected and need to be propagated to
.Nm smcrouted.
.It Nm join Ar IFNAME [SOURCE] GROUP
Join a multicast group on a given interface.  The source address is
optional, but if given a source specific (SSM) join is performed.
.It Nm leave Ar IFNAME [SOURCE] GROUP
Leave a multicast group on a given interface.  As with the join command,
above, the source address is optional.
.It Nm help [cmd]
Print a usage information message.
.It Nm kill
Stop (kill) running daemon.
.It Nm restart
Tell daemon to restart and reload its configuration file.  Same as
.Ar SIGHUP .
.It Nm show [groups|routes]
Show joined multicast groups or multicast routes, defaults to show
routes.  Can be combined with the
.Fl d
option to get details for each multicast route.
.It Nm version
Show program version.
.El
.Pp
A multicast route is defined by an input interface
.Ar IFNAME ,
the sender's unicast IP address
.Ar SOURCE ,
which is optional, the multicast group
.Ar GROUP
and a list of, at least one, output interface
.Ar IFNAME [IFNAME ...] .
.Pp
The sender's address and the multicast group must both be either IPv4
or IPv6 addresses.
.Pp
The output interfaces are not needed when removing routes using the
.Nm remove
command.  The first three parameters are sufficient to identify the
source of the multicast route.
.Pp
The intended purpose of
.Nm
is to aid in situations where dynamic multicast routing does not work
properly.  However, a dynamic multicast routing protocol is in nearly
all cases the preferred solution.  The reason for this is their ability
to translate Layer-3 signaling to Layer-2 and vice versa (IGMP or MLD).
.Pp
.Nm smcrouted
is capable of simple group join and leave by sending commands to the kernel.
The kernel then handles sending Layer-2 IGMP/MLD join and leave frames as needed.
This can be used for testing but is also useful sometimes to open up
multicast from the sender if located on a LAN with switches equipped
with IGMP/MLD Snooping.  Such devices will prevent forwarding of
multicast unless an IGMP/MLD capable router or multicast client is
located on the same physical port as you run
.Nm smcrouted
on.  However, this feature of
.Nm smcrouted
is only intended as a workaround, and only 20 groups can be joined this
way (kernel limit).  For bigger installations it is strongly recommended
to instead address the root cause, e.g. enable multicast router ports on
intermediate switches, or try the embedded multicast router discovery
feature of
.Nm smcrouted .
.Pp
To emulate a multicast client using
.Nm
you use the
.Nm join
and
.Nm leave
commands to issue join and leave commands for a given multicast group
on a given interface
.Ar IFNAME .
The
.Ar GROUP
may be given in an IPv4 or IPv6 address format.
.Pp
The command is passed to the daemon that passes it to the kernel. The
kernel then tries to join the multicast group
.Ar GROUP
on interface
.Ar IFNAME
by starting IGMP, or MLD for IPv6 group address, signaling on the given
interface.  This signaling may be received by routers/switches connected
on that network supporting IGMP/MLD multicast signaling and, in turn,
start forwarding the requested multicast stream eventually reach your
desired interface.
.Pp
.Nm Note:
when running multiple
.Nm smcrouted
instances, one per routing table on Linux, it is required to use the
.Fl I Ar NAME
option to both daemon and client.  This because the name of the IPC
socket used for communicating is composed from the identity.
.Sh CONFIGURATION FILE
.Nm smcrouted
supports reading and setting up multicast routes from a config file.
The default location is
.Ar /etc/smcroute.conf ,
but this can be overridden using the
.Fl f Ar FILE
command line option.
.Pp
The
.Ar IFNAME
argument below is the interface name, or an interface wildcard of the
form
.Ar eth+ ,
which matches
.Ar eth0 , eth10 ,
etc.  Wildcards are available for inbound interfaces.
.Pp
.Bd -unfilled -offset indent
#
# smcroute.conf example
#
# The configuration file supports joining multicast groups, to use
# Layer-2 signaling so that switches and routers open up multicast
# traffic to your interfaces.  Leave is not supported, remove the
# mgroup and SIGHUP your daemon, or send a specific leave command.
#
# NOTE: Use of the mgroup command should be avoided if possible.
#       Instead configure "router ports" or similar on the switches
#       or bridges on your LAN.  This to have them direct all the
#       multicast to your router, or direct select groups they have
#       such capabilities.  Usually MAC multicast filters exist.
#
#       The UNIX kernel usually limits the number of multicast groups
#       a socket/client can join.  In Linux, 20 mgroup lines can be
#       configured by default, but this can be changed with sysctl:
#
#           sysctl -w net.ipv4.igmp_max_memberships=30
#
# Similarly supported is setting mroutes.  Removing mroutes is not
# supported, remove/comment out the mroute from the .conf file, or
# send a remove command with smcroutectl.
#
# Syntax:
#   phyint IFNAME <enable|disable> [mrdisc] [ttl-threshold <1-255>]
#   mgroup from IFNAME [source ADDRESS] group MCGROUP
#   mroute from IFNAME [source ADDRESS] group MCGROUP[/LEN] to IFNAME [IFNAME ...]

# This example disables the creation of a multicast VIF for WiFi
# interface wlan0.  The kernel (at least Linux) sets the ALLMULTI
# flag for all interfaces that have a VIF enabled.  Hence, it can
# cause quite a bit of unnecessary traffic to reach the CPU if too
# many interfaces have a VIF (or MIF in IPv6 lingo).  Only enable
# interfaces required for inbound and outbound traffic.
# phyint wlan0 disable
phyint eth0 enable ttl-threshold 11
phyint eth1 enable ttl-threshold 3
phyint eth2 enable ttl-threshold 5
phyint virbr0 enable ttl-threshold 5

# The following example instructs the kernel to join the multicast
# group 225.1.2.3 on interface eth0.  Followed by setting up an
# mroute of the same multicast stream, but from the explicit sender
# 192.168.1.42 on the eth0 network and forward to eth1 and eth2.
#
mgroup from eth0                     group 225.1.2.3
mroute from eth0 source 192.168.1.42 group 225.1.2.3 to eth1 eth2

# Similar example, but using source-specific group join
mgroup from virbr0 source 192.168.123.110 group 225.1.2.4
mroute from virbr0 source 192.168.123.110 group 225.1.2.4 to eth0

# Here we allow routing of multicast to group 225.3.2.1 from ANY
# source coming in from interface eth0 and forward to eth1 and eth2.
# NOTE: Routing from ANY source is currently only available for IPv4
#       multicast.
mgroup from eth0 group 225.3.2.1
mroute from eth0 group 225.3.2.1 to eth1 eth2

# The previous is an example of the (*,G) support.  Such rules cause
# SMCRoute to dynamically add multicast routes to the kernel when the
# first frame of a stream reaches the router.  It is also possible to
# specify a range of such rules, again, note that this currently only
# works for IPv4.  Also, it is not possible to set a range of groups
# to join atm.
mroute from eth0 group 225.0.0.0/24 to eth1 eth2
.Ed
.Pp
Fairly simple. As usual, to identify the origin of the inbound multicast
we need the
.Ar IFNAME ,
the sender's IP address and, of course, the multicast group address,
.Ar MCGROUP .
The last argument is a list of outbound interfaces.
.Pp
The source address is optional for IPv4 multicast routes.  If omitted it
defaults to 0.0.0.0 (INADDR_ANY) and will cause
.Nm smcrouted
to dynamically add new routes, matching the group and inbound interface,
to the kernel.  This is an experimental feature which may not work as
intended, in particular not with 1:1 NAT.
.Pp
Following the UNIX tradition the file format supports comments starting
at the beginning of the line using a hash sign.  It is untested to have
comments at the end of a line, but should work.
.Pp
When starting up in debug mode,
.Nm smcrouted
logs the success of parsing each line and setting up a route.
.Sh LIMITS
The current version compiles and runs fine on Linux kernel version
2.4, 2.6 and 3.0. Known limits:
.Pp
.Bl -tag -width TERM -compact -offset indent
.It Cm Multicast routes
Depends on the kernel, more than 200, probably more than 1000
.It Cm Multicast group memberships
Max. 20, see caveat above
.El
.Pp
.Sh SIGNALS
.Nm smcrouted
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It Cm HUP
Restart and reload the configuration file.  All existing multicast
routes and groups are dropped.
.It Cm INT
Terminates execution gracefully.
.It Cm TERM
The same as INT.
.El
.Pp
For convenience in sending signals,
.Nm smcrouted
writes its process ID to
.Pa /var/run/smcroute.pid
upon startup.
.Pp
.Sh DEBUGGING
The most common problem when attempting to route multicast is the TTL.
Always start by verifying that the TTL of your multicast stream is not
set to 1, because the router decrements the TTL of an IP frame before
routing it.  Test your setup using
.Xr ping 8
or
.Xr iperf 1 .
Either of which is capable of creating multicast traffic with an
adjustable TTL.  Iperf in particular is useful since it can act both as
a multicast source (sender) and a multicast sink (receiver).  For more
advanced IP multicast testing the
.Xr omping 8
tool can be used.
.Pp
.Sh FILES
.Bl -tag -width /proc/net/ip6_mr_cache -compact
.It Pa /etc/smcroute.conf
Routes to be set when starting, or restarting
.Nm smcrouted
on
.Ar SIGHUP .
Like the PID file, the name of the configuration file may be different
depending on command line options given to the daemon.
.It Pa /var/run/smcroute.pid
Default PID file (re)created by
.Nm smcrouted
when it has started up and is ready to receive commands.  See also the
.Fl I Ar NAME
or
.Fl P Ar FILE
options which can change the default name.
.It Pa /var/run/smcroute.sock
IPC socket created by
.Nm smcrouted
for use by
.Nm smcroutectl .
Same caveats apply to this file as the previous two, command line
options to the daemon can change the file names.
.It Pa /proc/net/ip_mr_cache
Holds active IPv4 multicast routes.
.It Pa /proc/net/ip_mr_vif
Holds the IPv4 virtual interfaces used by the active multicast routing daemon.
.It Pa /proc/net/ip6_mr_cache
Holds active IPv6 multicast routes.
.It Pa /proc/net/ip6_mr_vif
Holds the IPv6 virtual interfaces used by the active multicast routing daemon.
.It Pa /proc/net/igmp
Holds active IGMP joins.
.It Pa /proc/net/igmp6
Holds active MLD joins.
.El
.Pp
.Sh SEE ALSO
.Xr mrouted 8 ,
.Xr pimd 8 ,
.Xr omping 8 ,
.Xr ping 8 ,
.Xr mcjoin 1 ,
.Xr iperf 1
.Sh AUTHORS
SMCRoute was created by Carsten Schill <carsten@cschill.de>.  IPv6
support by Todd Hayton <todd.hayton@gmail.com>.  FreeBSD support by
Micha Lenk <micha@debian.org>.
.Pp
.Nm smcrouted
is maintained by Joachim Nilsson <troglobit@gmail.com>, Todd Hayton
<todd.hayton@gmail.com>, Micha Lenk <micha@debian.org> and Julien BLACHE
<jblache@debian.org> at
.Ar https://github.com/troglobit/smcroute
.
.Sh TIPS
A lot of extra information is sent under the daemon facility and the
debug priority to the syslog daemon.  Use
.Cm smcrouted -s -l debug
to enable.