MROUTECTL(8) (smm)
MROUTECTL(8) System Manager's Manual (smm) MROUTECTL(8)

Control and status query tool for mrouted(8)

mroutectl [
] [
] [
] [

mroutectl help | kill | restart

mroutectl debug [
? | none | SYSTEM [

mroutectl log [
? | none | LEVEL

mroutectl show igmp [
interfaces | groups

mroutectl show interfaces

mroutectl show mfc

mroutectl show routes

mroutectl [
show status

mroutectl show version

mroutectl is the friendly control tool for mrouted(8). It can be used to query status, debug, restart, and kill a running mrouted. Commands can be abbreviated to the minimum unambiguous prefix; for example, s s for show status.

This program follows the usual UNIX command line syntax, with long options starting with two dashes (`-'). The options are as follows:
Detailed output, where applicable, see each command below.
Show usage instructions and exit.
--ident NAME
Connect to named mrouted instance.
Use plain table headings, no ANSI ctrl characters. When using watch(1), use watch -c option instead, it handles ANSI escape sequences.
Skip table headings altogether.
--ipc FILE
Override UNIX domain socket filename, the default on most systems is /var/run/mrouted.sock.
Show mrouted version that mroutectl is built against.

The following commands are available:
mroutectl debug [
? | none | SYSTEM [
Control mrouted subystem debugging at runtime. Multiple subsystems can be enabled, separate with comma. E.g.
mroutectl debug igmp,routes
The command returns a list of enabled subsystems. Without any debug argument, the command lists the currently enabled subsystems. To list all available subsystems, use
mroutectl debug ?
To disable all subsystems, use
mroutectl debug none
Available subsystems:
Debug inbound/outbout packets
Pruning operations, or pruned routes
Routing messages
Detailed routing information
Neighbor gossip
Debug kernel access
Debug routing cache
Debug timers
Show interface (VIF) debug messages
Debug multicast group memberships
Multicast traceroute information
Debug IGMP, including DVMRP, messages
Debug ICMP messages
Enable all subsystems (may trigger log rate limiter)
mroutectl help
Show usage instructions and exit.
mroutectl kill
Stop a running mrouted, similar to sending SIGTERM. mroutectl returns when the command has been delivered and mrouted has begun shutting down.
mroutectl log [
? | none | LEVEL
Control, query, or disable mrouted(8) log level. E.g.
mroutectl log debug
Without any argument, the command lists the current log level. To list all available log levels, use
mroutectl log ?
To disable logging completely, use
mroutectl log none
Available log levels:
Disable all logging
Error conditions
Warning conditions
Normal but significant condition (Default)
Debug-level messages
mroutectl restart
Restart daemon and reload /etc/mrouted.conf, like sending SIGHUP to mrouted(8)
mroutectl show compat
Previously available as mrouted -r, as well as sending SIGUSR1 to mrouted(8), to get output in /var/run/mrouted/mrouted.dump. Note: this command is only intended for developers and hard core mroutectl users, it can be hard to read. See below EXAMPLES section for more help.
mroutectl show igmp [
interfaces | groups
Show IGMP status for interfaces and groups. To show only the interfaces or groups, use the following sub-arguments:
Show IGMP interface status; elected IGMP querier, expiration timer, and IGMP version used per link, number of joined groups per link.
Show IGMP group memberships per interface; last reporter, and expiration timer.
mroutectl show interfaces
Show interface table; address, state, cost (metric) for interface, threshold TTL (required for crossing), uptime (still TODO), and interface flags like: Querier, Leaf, etc.
mroutectl show mfc
Show multicast forwarding cache, i.e., the actual multicast routing table. Use -d for more detailed output, including pruning information. The 'P' and ':p' shows upstream and downstream prunes, respectively.
mroutectl show neighbor
Show information about DVMRP neighbors.
mroutectl show routes
Show DVMRP routing table, i.e. the unicast routing table used for RPF calculations.
mroutectl [
show status
Show mrouted(8) status summary, default.
mroutectl show version
Show version, and uptime if -d is given, of running mrouted

This section shows example interactions with mroutectl for some of the supported commands.

mroutectl show iface

Address         Interface      State Cost TTL    Uptime Flags        eth0              Up    1   1  00:00:00      eth1              Up    1   1  00:00:00 QL

mroutectl show neighbor

Neighbor        Interface       Version Flags    Uptime Expire        eth0            3.255   G       0:00:16    25s        eth0            3.255   G       0:00:17    30s

mroutectl -d show routes

Origin          Neighbor        Interface        Cost   Expire 
192.168.0/24        eth0                3      30s 
172.16.1/24        eth0                2      30s 
172.16.0/24     Local           eth1                1      60s 
10.0.1/24       Local           eth0                1      60s 
10.0.0/24        eth0                2      30s

mroutectl show igmp iface

Interface         Querier          Version  Groups  Expire 
eth1              Local                  3       1   Never 
eth0                   3       0    220s

mroutectl show igmp group

Interface         Group            Last Reporter    Expire 
eth1            190s

mroutectl -d show mfc

Origin          Group           Inbound         <>    Uptime   Expire  Outbound 
192.168.0/24       eth0            P    0:10:42  0:04:03 
192.168.0/24       eth0            P    0:10:42  0:03:42 
192.168.0/24       eth0            P    0:10:42  0:04:49 
172.16.1/24       eth0                 0:10:51  0:00:24  eth1 
192.168.0/24       eth0                 0:10:42  0:01:51  eth1 
172.16.1/24       eth0            P    0:10:51  0:03:13 
192.168.0/24       eth0            P    0:10:42  0:01:16 
172.16.1/24       eth0            P    0:10:51  0:02:07 
192.168.0/24       eth0            P    0:10:42  0:00:09 
Source          Group           Inbound               Uptime  Packets     Bytes       eth0                 0:10:51     6518    834304       eth0                 0:10:42     6425    822400

mroutectl -dp show compat

The output from the compat command is very verbose and looks quite scary at first sight. It is kept for backwards compatibility and developer debug purposes and has a lot of details encoded. See below for a breakdown.
Virtual Interface Table 
 VIF  Local-Address                    Metric  Thresh  Flags 
  0      subnet: 36.2          1       1    querier 
                   pkts in: 3456 
                  pkts out: 2322323 
  1     subnet: 36.11         1       1    querier 
                   pkts in: 345 
                  pkts out: 3456 
  2      tunnel:     3       1 
                     peers: (2.2) 
                boundaries: 239.0.1 
                          : 239.1.2 
                   pkts in: 34545433 
                  pkts out: 234342 
  3	    tunnel:	  3       16 
Multicast Routing Table (1136 entries) 
 Origin-Subnet   From-Gateway    Metric Tmr In-Vif  Out-Vifs 
 36.2                               1    45    0    1* 2  3* 
 36.8            4    15    2    0* 1* 3* 
 36.11                              1    20    1    0* 2  3* 
In this example, there are four VIFs connecting to two subnets and two tunnels. The VIF 3 tunnel is not in use (no peer address). The VIF 0 and VIF 1 subnets have some groups present; tunnels never have any groups. This instance of mrouted is the one responsible for sending periodic group membership queries on the VIF 0 and VIF 1 subnets, as indicated by the "querier" flags. The list of boundaries indicate the scoped addresses on that interface. A count of the number of incoming and outgoing packets is also shown at each interface.
Associated with each subnet from which a multicast datagram can originate is the address of the previous hop router (unless the subnet is directly- connected), the metric of the path back to the origin, the amount of time since we last received an update for this subnet, the incoming VIF for multicasts from that origin, and a list of outgoing VIFs. "*" means that the outgoing VIF is connected to a leaf of the broadcast tree rooted at the origin, and a multicast datagram from that origin will be forwarded on that outgoing VIF only if there are members of the destination group on that leaf.
mrouted also maintains a copy of the kernel forwarding cache table. Entries are created and deleted by mrouted.
The cache tables look like this:
Multicast Routing Cache Table (147 entries) 
 Origin             Mcast-group     CTmr  Age Ptmr IVif Forwvifs 
 13.2.116/22     3m   2m    -  0    1 
 138.96.48/21     5m   2m    -  0    1 
 128.9.160/20     3m   2m    -  0    1 
 198.106.194/24     9m  28s   9m  0P 
Each entry is characterized by the origin subnet number and mask and the destination multicast group.
The 'CTmr' field indicates the lifetime of the entry. The entry is deleted from the cache table when the timer decrements to zero. The 'Age' field is the time since this cache entry was originally created. Since cache entries get refreshed if traffic is flowing, routing entries can grow very old.
The 'Ptmr' field is simply a dash if no prune was sent upstream, or the amount of time until the upstream prune will time out. The 'Ivif' field indicates the incoming VIF for multicast packets from that origin.
Each router also maintains a record of the number of prunes received from neighboring routers for a particular source and group.
If there are no members of a multicast group on any downward link of the multicast tree for a subnet, a prune message is sent to the upstream router. They are indicated by a "P" after the VIF number.
The Forwvifs field shows the interfaces along which datagrams belonging to the source-group are forwarded.
A "p" indicates that no datagrams are being forwarded along that interface. An unlisted interface is a leaf subnet with no members of the particular group on that subnet.
A "b" on an interface indicates that it is a boundary interface, i.e. traffic will not be forwarded on the scoped address on that interface. An additional line with a ‘>’ as the first character is printed for each source on the subnet.
Note that there can be many sources in one subnet.

Main configuration file.
UNIX-domain socket used for communication with mrouted(8)

mrouted(8), mrouted.conf(5)

mroutectl was written by Joachim Wiberg ⟨⟩.
January 1, 2021 Debian