Reporting a camera interop issue - scottlamb/moonfire-nvr GitHub Wiki

Moonfire NVR strives to work with just about any IP camera that supports RTSP. But cameras' RTSP implementations often have unique bugs that require workarounds in Moonfire or its underlying RTSP library, Retina.

When reporting these problems, please include any logs that describe the problem, for example:

Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: tokio-runtime-worker streamer{stream="back_east-main"}: moonfire_nvr::streamer: sleeping for 1 s after error err=UNKNOWN
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: caused by: RTSP framing error: Invalid RTSP message; buffered:
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: Length: 3860 (0xf14) bytes
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0000:   14 3f 97 d1  02 4f 66 c3  03 8b 6e 8d  b0 c7 47 50   .?...Of...n...GP
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0010:   f7 c4 88 be  84 ba 1d bc  e5 b6 95 f2  17 d9 0c 3b   ...............;
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0020:   e0 f2 41 fd  16 ed da 3e  c7 c0 09 09  24 a0 e8 3a   ..A....>....$..:
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0030:   1e 77 12 2a  a2 42 76 50  a9 63 50 9c  89 b9 b6 7d   .w.*.BvP.cP....}
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0040:   79 62 ca 29  d1 5c 5b 7b  89 bb ad 61  13 4e 0f 3e   yb.).\[{...a.N.>
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0050:   58 4a e7 86  6e d1 78 b9  65 54 bc 85  18 76 6d f3   XJ..n.x.eT...vm.
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0060:   f8 2b d7 28  5d 80 ec c3  92 a2 de d4  7e c0 51 09   .+.(].......~.Q.
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: 0070:   f3 9c c2 7b  12 c5 1a 0e  14 59 e3 6b  d6 f1 f9 74   ...{.....Y.k...t
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: ...3732 (0xe94) bytes not shown...
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: conn: 192.168.5.206:44438(me)->192.168.5.102:554@2026-01-05T21:00:06.839683711Z
Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: msg: 14803846996@2026-01-06T05:05:36.381287682Z

These errors are meant to both describe the error and help find the right spot within a packet capture. Which brings us to:

Packet captures

pcap files are like freshly baked chocolate chip cookies. Everybody loves them. — Julia Evans

The gold standard for reporting a network interoperability problem is a packet capture: a record of every data packet sent at the IP (or even Ethernet) level between the devices in question. There are many ways packet captures are helpful:

They give the full session context to help understand the error and reproduce the scenario in unit tests.
They can show lower-level problems than are visible to Moonfire itself. For example, if the TCP window fills, and then the cameras' socket send buffer fills, cameras often will just skip bytes, messing up the RTSP framing. This TCP-level effect isn't visible to the receiver (Moonfire) but is clear in the packet capture.
They can capture sessions initiated not just by Moonfire but by other software that might interoperate with the cameras successfully: ffmpeg, gstreamer, VLC, MediaMTX, etc.
They can be fed into the many tools designed to examine packet captures.

A warning

Packet captures contain information you might not want to share with the whole Internet:

your camera's password. (It's not in plaintext, but HTTP digest authentication does not use strong cryptography by today's standards.)
IP addresses and MACs of your camera, your Moonfire machine, and sometimes routers between.
any actual video and audio that made it through.
unrelated network traffic, depending on your filter expression. (Below we show how to make a filter to avoid this.)

It's okay if you don't feel comfortable putting this information in a Github issue attachment:

Moonfire's author is happy to receive packet captures privately (email [email protected]) and keep these details confidential.
There are likely techniques we could use to redact data.
Moonfire's author would also be happy to talk you through analyzing the packet capture yourself.

How to capture

You can create a packet capture with Wireshark's GUI or the tcpdump CLI utility. It's usually easiest to do this on the same machine running Moonfire. You need two pieces of information:

the network interface to capture on—which should match the address Moonfire used to talk to the camera.
a filter rule for the packets to capture—typically every packet to or from to the camera's IP address.

In the error above, note the conn line:

Jan 05 21:05:36 rock-5b moonfire-nvr[95036]: conn: 192.168.5.206:44438(me)->192.168.5.102:554@2026-01-05T21:00:06.839683711Z
                                                   mmmmmmmmmmmmm            ccccccccccccc
                                                   Moonfire's IP            camera's IP

On Linux, we can use the ip addr command to find the name of the network interface Moonfire used. Typically this is a name like eth0 or enp3s0. In this case we're using up a virtual interface surveil running on top of the physical interface enm:

$ ip addr show to 192.168.5.205
3: surveil@enm: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    inet 192.168.5.205/24 brd 192.168.5.255 scope global dynamic surveil
       valid_lft 35391sec preferred_lft 35391sec

For the filter, we'll use host 192.168.5.102 to capture everything to and from the camera.

We can capture with tcpdump, starting it before we have a problem:

$ sudo tcpdump -Uw bad-capture.pcap -i surveil 'host 192.168.5.102'
...wait for the problem to occur, then...
^C (hit ctrl-C to stop the capture)

Then you can open the file with Wireshark to see that it...

captured packets going to and from the camera at all
captured the time range Moonfire is complaining about
captured only data you're comfortable sharing