MROUTECTL(8)

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

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 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:
    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
This section shows example interactions with mroutectl for some of the supported commands.

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