File: smcroute.8

package info (click to toggle)
smcroute 2.0.0-5
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 636 kB
  • ctags: 221
  • sloc: ansic: 2,296; sh: 1,310; perl: 161; makefile: 61
file content (305 lines) | stat: -rw-r--r-- 9,917 bytes parent folder | download | duplicates (2)
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
.Dd $Mdocdate: November 01 2011 $
.Dt SMCROUTE 8 SMM
.Os
.Sh NAME
.Nm smcroute
.Nd SMCRoute, a static multicast router
.Sh SYNOPSIS
.Nm smcroute
.Op OPTIONS
.Op COMMANDS
.Sh DESCRIPTION
.Nm
is a command line tool to manipulate the multicast routes of a UNIX
kernel. It supports both IPv4 and IPv6 multicast routing. SMCRoute 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
Generally multicast routes exists in the kernel only as long as smcroute
or another multicast routing daemon is running. Only one multicast
routing daemon can be active at a time, so it's impossible to run
smcroute and, e.g.,
.Nm mrouted
at the same time.
.Pp
Because
.Nm
modifies the kernel routing table it needs to run with full
.Ar superuser rights .
Which also means that the same applies to client operations, to be
able to communicate with the daemon.
.Ss WARNING
By using multiple output interfaces (traffic multiplication), using the
input interface also as output interface (direct loop) or constructing
some other forms of indirect loops you can easily flood your networks!
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d
Starts the smcroute daemon before any of the optional following commands
are executed. Please note, if started with the
.Fl n
flag no commands specified on the command line will be run.
.It Fl n
Run in foreground, do not detach from the calling terminal.  This also
means that any further commands from that command line are run.  Option
flags, however, are accepted, but not command flags.
.It Fl f Ar FILE
Specify an alternative configuration file, instead of the default
.Pa /etc/smcroute.conf .
.It Fl v
Display version and enable verbose logs.  This gives a more verbose
output in some error situations.  Do not expect too much, see syslog
instead.
.It Fl D
Enable additional debug messages.  Do not expect too much, see syslog
instead.
.It Fl h
Print a help message and exit.
.It Fl k
Stop (kill) running daemon.
.El
.Pp
The 
.Fl d
option to smcroute starts the smcroute daemon. It can be started in the
foreground using the
.Fl n
option. The
.Fl k
option will terminate a running daemon.  The 
.Fl f Ar FILE
option can be used to tell the daemon to setup routes from a conf
file. By default it looks for /etc/smcroute.conf
.Sh COMMANDS
The following are commands that can only be passed to an already running daemon.
.Bl -tag -width Ds
.It Fl a Ar IFNAME SOURCE GROUP IFNAME [IFNAME ...]
Add a kernel multicast route from {IFNAME, SOURCE & GROUP} to a list of,
at least one, outbound IFNAME.  The interfaces can be any network
interface as listed by 'ifconfig' or 'ip link list' (incl. tunnel
interfaces), but not the loopback interface.  Please note that the
.Ar SOURCE
address is the unicast IPv4 or IPv6 source address of the multicast
sender! The 
.Ar GROUP
can be either an IPv4 or IPv6 formatted multicast group address.
.It Fl r Ar IFNAME SOURCE GROUP
Remove a kernel multicast route.
.It Fl j Ar IFNAME GROUP
Join a multicast group on a given interface.
.It Fl l Ar IFNAME GROUP
Leave a multicast group on a given interface.
.El
.Pp
To be able to add/remove routes or join/leave multicast groups the
.Nm
daemon must run.
.Pp
Multicast routes can be added with the 
.Fl a 
command and removed with the 
.Fl r
command. 
.Pp
A multicast route is defined by an input interface
.Ar IFNAME ,
the sender's unicast IP address
.Ar SOURCE ,
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 IPv4 addresses
or IPv6 addresses.  If IPv4 addresses are specified then SMCRoute will
operate on the IPv4 multicast routes. If IPv6 addresses are specified
then SMCRoute will operate on the IPv6 multicast routes.
.Pp
The output interfaces are not needed when removing routes using the
.Fl r
command. The first three parameters are sufficient to identify the
source of the multicast route. 
.Pp
The intended purpose of SMCRoute is to aid in situations where dynamic
multicast routing does not work properly.  However, dynamic multicast routing
is in nearly all cases the preferred solution.
.Pp
.Nm
can also send simple group join and leave commands to the kernel. As a
result the kernel will send Layer-2 IGMP join and leave frames. 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
on.
.Pp
To emulate a multicast client using
.Nm
you use the
.Fl j
and
.Fl l
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
With this command
.Nm
allows the integration of nodes that need static multicast routing into
dynamic multicast routing domains.
.Pp
.Sh CONFIGURATION FILE
From version 1.98.0 smcroute 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
.Bd -unfilled -offset left
#
# 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.
#
# Similarily supported is setting mroutes. Removing mroutes is not
# supported, remove/comment out the mroute or send a remove command.
#
# Syntax:
#   mgroup from IFNAME group MCGROUP
#   mroute from IFNAME [source ADDRESS] group MCGROUP to IFNAME [IFNAME ...]
#
# 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 group 225.1.2.3 source 192.168.1.42 to eth1 eth2

# 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
.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
From 1.99.0 the sender's IP address is actually optional for IPv4
multicast routes. If omitted it defaults to 0.0.0.0 (INADDR_ANY) and
will cause
.Nm
to dynamically at runtime add new routes, matching the group and inbound
interface, to the kernel. This feauture is experimental.
.Pp
Following the standard UNIX tradition the file format support comments
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, the daemon by default lists 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
More than 200
.It Cm Multicast group membership
Max. 20
.El
.Pp
.Sh SIGNALS
.Nm
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It HUP
Restarts
.Nm .
The configuration file is reread every time this signal is received.
.It INT
Terminates execution gracefully.
.It TERM
The same as INT.
.El
.Pp
For convenience in sending signals,
.Nm
writes its process ID to
.Pa /var/run/smcroute.pid
upon startup.
.Pp
.Sh FILES
.Bl -tag -width /proc/net/ip6_mr_cache -compact
.It Pa /etc/smcroute.conf
Routes to be added/restored when starting, or restarting the daemon on
SIGHUP.
.It Pa /var/run/smcroute.pid
Pidfile (re)created by
.Nm
daemon when it has started up and is ready to receive commands.
.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 /var/run/smcroute 
IPC socket created by the smcroute 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
.Sh BUGS
The English wording of this man page.
.Sh AUTHORS
Originally written by Carsten Schill <carsten@cschill.de>.
Support for IPv6 was added by Todd Hayton <todd.hayton@gmail.com>.
Support for FreeBSD was added by Micha Lenk <micha@debian.org>.
.Pp
SMCRoute 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.