MROUTECTL(8)

💅 MROUTECTL(8) — Control and status query tool for mrouted(8) 💅

System Manager's Manual — okay bestie, this is the whole vibe of mroutectl.

🎀 NAME 🎀

mroutectl — Control and status query tool for mrouted(8)

✨ SYNOPSIS ✨

mroutectl [-dpthv] [-i NAME] [-u FILE] [COMMAND]

mroutectl help | kill | restart

mroutectl debug [? | none | SYSTEM [,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

🌸 DESCRIPTION 🌸

Okay so 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. Slay. 💅

💖 OPTIONS 💖

This program follows the usual UNIX command line syntax, with long options starting with two dashes (-). The options are as follows:

• -d, --detail — Detailed output, where applicable, see each command below.
• -h, --help — Show usage instructions and exit.
• -i, --ident NAME — Connect to named mrouted instance.
• -p, --plain — Use plain table headings, no ANSI ctrl characters. When using watch(1), use watch -c option instead, it handles ANSI escape sequences.
• -t, --no-heading — Skip table headings altogether.
• -u, --ipc FILE — Override UNIX domain socket filename, the default on most systems is /var/run/mrouted.sock.
• -v, --version — Show mrouted version that mroutectl is built against.

🕹️ COMMANDS 🕹️

The following commands are available:

mroutectl debug [? | none | SYSTEM [,SYSTEM]]

Control mrouted subsystem 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:

• packet | pkt — Debug inbound/outbout packets
• pruning | prunes — Pruning operations, or pruned routes
• routing | routes — Routing messages
• route-detail | rtdetail — Detailed routing information
• neighbors | peers — Neighbor gossip
• kernel — Debug kernel access
• cache — Debug routing cache
• timer — Debug timers
• interface | vif — Show interface (VIF) debug messages
• membership | groups — Debug multicast group memberships
• traceroute | mtrace — Multicast traceroute information
• igmp — Debug IGMP, including DVMRP, messages
• icmp — Debug ICMP messages
• all | 3 — 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:

• none — Disable all logging
• error — Error conditions
• warning — Warning conditions
• notice — Normal but significant condition (Default)
• info — Informational
• debug — 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:

• interfaces — Show IGMP interface status; elected IGMP querier, expiration timer, and IGMP version used per link, number of joined groups per link.
• groups — 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

💖 EXAMPLES 💖

Bestie, these are the actual example interactions with mroutectl for some of the supported commands. The tables are real, the vibes are immaculate, and every number stays exactly where it was. 🫶

---

🌸 mroutectl show iface

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

---

🦋 mroutectl show neighbor

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

---

✨ mroutectl -d show routes

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

---

🎀 mroutectl show igmp iface

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

---

🌈 mroutectl show igmp group

         Interface         Group            Last Reporter    Expire
         eth1              225.1.2.6        172.16.0.10        190s

---

🔥 mroutectl -d show mfc

         Origin          Group           Inbound         <>    Uptime   Expire  Outbound
         192.168.0/24    225.1.2.3       eth0            P    0:10:42  0:04:03
         192.168.0/24    225.1.2.4       eth0            P    0:10:42  0:03:42
         192.168.0/24    225.1.2.5       eth0            P    0:10:42  0:04:49
         172.16.1/24     225.1.2.6       eth0                 0:10:51  0:00:24  eth1
         192.168.0/24    225.1.2.6       eth0                 0:10:42  0:01:51  eth1
         172.16.1/24     225.1.2.7       eth0            P    0:10:51  0:03:13
         192.168.0/24    225.1.2.7       eth0            P    0:10:42  0:01:16
         172.16.1/24     225.1.2.8       eth0            P    0:10:51  0:02:07
         192.168.0/24    225.1.2.8       eth0            P    0:10:42  0:00:09

         Source          Group           Inbound               Uptime  Packets     Bytes
         172.16.1.11     225.1.2.6       eth0                 0:10:51     6518    834304
         192.168.0.10    225.1.2.6       eth0                 0:10:42     6425    822400

---

😭 mroutectl -dp show compat

Okay, so 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 it has a lot of details encoded. See the breakdown below, bestie. 💀

      Virtual Interface Table
       VIF  Local-Address                    Metric  Thresh  Flags
        0   36.2.0.8      subnet: 36.2          1       1    querier
                          groups: 224.0.2.1
                                  224.0.0.4
                         pkts in: 3456
                        pkts out: 2322323

        1   36.11.0.1     subnet: 36.11         1       1    querier
                          groups: 224.0.2.1
                                  224.0.1.0
                                  224.0.0.4
                         pkts in: 345
                        pkts out: 3456

        2   36.2.0.8      tunnel: 36.8.0.77     3       1
                           peers: 36.8.0.77 (2.2)
                      boundaries: 239.0.1
                                : 239.1.2
                         pkts in: 34545433
                        pkts out: 234342

        3   36.2.0.8      tunnel: 36.6.8.23     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            36.8.0.77          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        224.2.127.255     3m   2m    -  0    1
>13.2.116.19
>13.2.116.196
 138.96.48/21       224.2.127.255     5m   2m    -  0    1
>138.96.48.108
 128.9.160/20       224.2.127.255     3m   2m    -  0    1
>128.9.160.45
 198.106.194/24     224.2.135.190     9m  28s   9m  0P
>198.106.194.22

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. 👑

---

🎀 FILES 🎀

• /etc/mrouted.conf — Main configuration file.
• /var/run/mrouted.sock — Unix-domain socket used for communication with mrouted(8).

---

🦋 SEE ALSO 🦋

mrouted(8), mrouted.conf(5)

---

👑 AUTHORS 👑

mroutectl was written by Joachim Wiberg <mailto:troglobit@gmail.com>.

---

Source/version vibes: Debian, dated Jan 1, 2021, page MROUTECTL(8) — iconic, no cap. 💅✨🫶