Promiscuous: Difference between revisions

Latest revision as of 16:48, 8 January 2026

Promiscuous mode allows a network interface to capture all packets on the wire, not just those addressed to its MAC address. This is essential for certain VoIPmonitor deployment scenarios.

When is Promiscuous Mode Required?

Traffic Mirroring Method	Promiscuous Mode Required?	Reason
SPAN / Port Mirroring	YES	Mirrored packets retain original MAC addresses
RSPAN	YES	Same as SPAN but across VLANs
Network TAP	YES	TAP copies raw Layer 2 frames
ERSPAN	No	Traffic encapsulated in GRE, addressed to sensor IP
GRE Tunnel	No	Tunnel packets addressed to sensor IP
TZSP	No	UDP encapsulation to sensor IP
VXLAN	No	UDP encapsulation to sensor IP
On-host capture	No	Sensor runs on PBX, sees own traffic natively

ℹ️ Note: For Layer 3 tunneling methods (ERSPAN, GRE, TZSP, VXLAN), the encapsulated traffic is addressed directly to the sensor's IP. The OS receives these packets normally and VoIPmonitor decapsulates them automatically.

Checking Current Status

# Check if promiscuous mode is enabled
ip link show eth0 | grep -i promisc

# Alternative: look for PROMISC flag in output
ip link show eth0
# Output includes: ... UP,BROADCAST,RUNNING,PROMISC ...

Enabling Promiscuous Mode

Temporary (Until Reboot)

# Enable
ip link set dev eth0 promisc on

# Disable
ip link set dev eth0 promisc off

Persistent Configuration

The sensor's install-script.sh attempts to configure this automatically, but may fail on some systems. Manual configuration options:

Method 1: Netplan (Ubuntu 18.04+)

Edit /etc/netplan/01-netcfg.yaml:

network:
  ethernets:
    eth0:
      # ... existing config ...
      # Add post-up script
  version: 2

Then create /etc/networkd-dispatcher/routable.d/50-promisc:

#!/bin/bash
ip link set dev eth0 promisc on

chmod +x /etc/networkd-dispatcher/routable.d/50-promisc

Method 2: systemd service

Create /etc/systemd/system/promisc.service:

[Unit]
Description=Enable promiscuous mode on eth0
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/ip link set dev eth0 promisc on
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now promisc.service

Method 3: rc.local (Legacy)

Add to /etc/rc.local before exit 0:

/sbin/ip link set dev eth0 promisc on

Verification

After enabling, verify traffic is visible:

# Quick test with tcpdump
sudo tcpdump -i eth0 -c 10 "port 5060"

# More detailed with tshark
tshark -i eth0 -Y "sip || rtp" -n -c 20

If you see SIP/RTP packets, promiscuous mode is working correctly.

Troubleshooting

Problem	Solution
`PROMISC` flag not showing after enable	Check if interface exists: `ip link show`. Verify interface name matches config.
Traffic visible in tcpdump but not in VoIPmonitor	Check `interface` directive in `/etc/voipmonitor.conf` matches. See Sniffer_troubleshooting.
Promiscuous mode resets after reboot	Use persistent configuration method above.
"Permission denied" when enabling	Run command as root or with `sudo`.
No traffic even with promisc enabled	Verify SPAN/mirror configuration on switch. See Sniffer_troubleshooting.

⚠️ Warning: Security: Promiscuous mode exposes the interface to all network traffic. Only enable on dedicated monitoring interfaces, not on production servers exposed to untrusted networks.

AI Summary for RAG

Summary: Promiscuous mode allows a network interface to capture all packets regardless of destination MAC address. It is REQUIRED for Layer 2 mirroring methods (SPAN, RSPAN, hardware TAP) because mirrored packets retain their original MAC addresses. It is NOT required for Layer 3 tunneling methods (ERSPAN, GRE, TZSP, VXLAN) because these encapsulate traffic in packets addressed directly to the sensor's IP. Enable with ip link set dev eth0 promisc on. For persistence, use systemd service, netplan dispatcher, or rc.local. Verify with ip link show eth0 looking for PROMISC flag.

Keywords: promiscuous mode, promisc, SPAN, RSPAN, port mirroring, network TAP, packet capture, ip link, interface configuration, ERSPAN, GRE, TZSP, VXLAN, Layer 2, Layer 3, MAC address, persistent configuration, systemd, netplan

Key Questions:

Do I need promiscuous mode for VoIPmonitor?
How do I enable promiscuous mode on Linux?
Does ERSPAN require promiscuous mode?
How do I make promiscuous mode persistent after reboot?
How do I check if promiscuous mode is enabled?
Why is VoIPmonitor not seeing SPAN traffic?
What is the difference between SPAN and ERSPAN for promiscuous mode?

@@ Line 1: / Line 1: @@
-{{DISPLAYTITLE:Troubleshooting: No Calls Being Sniffed}}
+{{DISPLAYTITLE:Promiscuous Mode for Packet Capture}}
-'''This guide provides a systematic, step-by-step process to diagnose why the VoIPmonitor sensor might not be capturing any calls. Follow these steps in order to quickly identify and resolve the most common issues.'''
+'''Promiscuous mode allows a network interface to capture all packets on the wire, not just those addressed to its MAC address. This is essential for certain VoIPmonitor deployment scenarios.'''
-== Step 1: Is the VoIPmonitor Service Running Correctly? ==
+== When is Promiscuous Mode Required? ==
-First, confirm that the sensor process is active and loaded the correct configuration file.
-;1. Check the service status (for modern systemd systems):
+{| class="wikitable"
-<pre>systemctl status voipmonitor</pre>
+|-
-Look for a line that says <code>Active: active (running)</code>. If it is inactive or failed, try restarting it with `systemctl restart voipmonitor` and check the status again.
+! Traffic Mirroring Method !! Promiscuous Mode Required? !! Reason
+|-
+| '''SPAN / Port Mirroring''' || '''YES''' || Mirrored packets retain original MAC addresses
+|-
+| '''RSPAN''' || '''YES''' || Same as SPAN but across VLANs
+|-
+| '''Network TAP''' || '''YES''' || TAP copies raw Layer 2 frames
+|-
+| '''ERSPAN''' || No || Traffic encapsulated in GRE, addressed to sensor IP
+|-
+| '''GRE Tunnel''' || No || Tunnel packets addressed to sensor IP
+|-
+| '''TZSP''' || No || UDP encapsulation to sensor IP
+|-
+| '''VXLAN''' || No || UDP encapsulation to sensor IP
+|-
+| '''On-host capture''' || No || Sensor runs on PBX, sees own traffic natively
+|}
-;2. Verify the running process:
+{{Note|For Layer 3 tunneling methods (ERSPAN, GRE, TZSP, VXLAN), the encapsulated traffic is addressed directly to the sensor's IP. The OS receives these packets normally and VoIPmonitor decapsulates them automatically.}}
-<pre>ps aux | grep voipmonitor</pre>
-This command will show the running process and the exact command line arguments it was started with. Critically, ensure it is using the correct configuration file, for example: <code>--config-file /etc/voipmonitor.conf</code>. If it is not, there may be an issue with your startup script.
-== Step 2: Is Network Traffic Reaching the Server? ==
+== Checking Current Status ==
-If the service is running, the next step is to verify if the VoIP packets (SIP/RTP) are actually arriving at the server's network interface. The best tool for this is `tshark` (the command-line version of Wireshark).
-;1. Install tshark:
+<syntaxhighlight lang="bash">
-<pre>
+# Check if promiscuous mode is enabled
-# For Debian/Ubuntu
+ip link show eth0 | grep -i promisc
-apt-get update && apt-get install tshark
-# For CentOS/RHEL/AlmaLinux
+# Alternative: look for PROMISC flag in output
-yum install wireshark
+ip link show eth0
-</pre>
+# Output includes: ... UP,BROADCAST,RUNNING,PROMISC ...
+</syntaxhighlight>
-;2. Listen for SIP traffic on the correct interface:
+== Enabling Promiscuous Mode ==
-Replace `eth0` with the interface name you have configured in `voipmonitor.conf`.
-<pre>
-tshark -i eth0 -Y "sip || rtp" -n
-</pre>
-*'''If you see a continuous stream of SIP and RTP packets''', it means traffic is reaching the server, and the problem is likely in VoIPmonitor's configuration (see Step 4).
-*'''If you see NO packets''', the problem lies with your network configuration. Proceed to Step 3.
-== Step 3: Troubleshoot Network and Interface Configuration ==
+=== Temporary (Until Reboot) ===
-If `tshark` shows no traffic, it means the packets are not being delivered to the operating system correctly.
-;1. Check if the interface is UP:
+<syntaxhighlight lang="bash">
-Ensure the network interface is active.
+# Enable
-<pre>ip link show eth0</pre>
+ip link set dev eth0 promisc on
-The output should contain the word `UP`. If it doesn't, bring it up with:
-<pre>ip link set dev eth0 up</pre>
-;2. Check for Promiscuous Mode (for SPAN/RSPAN Mirrored Traffic):
+# Disable
-'''Important:''' Promiscuous mode requirements depend on your traffic mirroring method:
+ip link set dev eth0 promisc off
+</syntaxhighlight>
-* '''SPAN/RSPAN (Layer 2 mirroring):''' The network interface '''must''' be in promiscuous mode. Mirrored packets retain their original MAC addresses, so the interface would normally ignore them. Promiscuous mode forces the interface to accept all packets regardless of destination MAC.
+=== Persistent Configuration ===
-* '''ERSPAN/GRE/TZSP/VXLAN (Layer 3 tunnels):''' Promiscuous mode is '''NOT required'''. These tunneling protocols encapsulate the mirrored traffic inside IP packets that are addressed directly to the sensor's IP address. The operating system receives these packets normally, and VoIPmonitor automatically decapsulates them to extract the inner SIP/RTP traffic.
+The sensor's <code>install-script.sh</code> attempts to configure this automatically, but may fail on some systems. Manual configuration options:
-For SPAN/RSPAN deployments, check the current promiscuous mode status:
+'''Method 1: Netplan (Ubuntu 18.04+)'''
-<pre>ip link show eth0</pre>
-Look for the `PROMISC` flag.
-Enable promiscuous mode manually if needed:
+Edit <code>/etc/netplan/01-netcfg.yaml</code>:
-<pre>ip link set dev eth0 promisc on</pre>
+<syntaxhighlight lang="yaml">
-If this solves the problem, you should make the change permanent. The `install-script.sh` for the sensor usually attempts to do this, but it can fail.
+network:
+  ethernets:
+    eth0:
+      # ... existing config ...
+      # Add post-up script
+  version: 2
+</syntaxhighlight>
-;3. Verify Your SPAN/Mirror/TAP Configuration:
+Then create <code>/etc/networkd-dispatcher/routable.d/50-promisc</code>:
-This is the most common cause of no traffic. Double-check your network switch or hardware tap configuration to ensure:
+<syntaxhighlight lang="bash">
-* The correct source ports (where your PBX/SBC is connected) are being monitored.
+#!/bin/bash
-* The correct destination port (where your VoIPmonitor sensor is connected) is configured.
+ip link set dev eth0 promisc on
-* If you are monitoring traffic across different VLANs, ensure your mirror port is configured to carry all necessary VLAN tags (often called "trunk" mode).
+</syntaxhighlight>
+<syntaxhighlight lang="bash">
+chmod +x /etc/networkd-dispatcher/routable.d/50-promisc
+</syntaxhighlight>
-== Step 4: Check the VoIPmonitor Configuration ==
+'''Method 2: systemd service'''
-If `tshark` sees traffic but VoIPmonitor does not, the problem is almost certainly in `voipmonitor.conf`.
-;1. Check the `interface` directive:
+Create <code>/etc/systemd/system/promisc.service</code>:
-:Make sure the `interface` parameter in `/etc/voipmonitor.conf` exactly matches the interface where you see traffic with `tshark`. For example: `interface = eth0`.
+<syntaxhighlight lang="ini">
+[Unit]
+Description=Enable promiscuous mode on eth0
+After=network.target
-;2. Check the `sipport` directive:
+[Service]
-:By default, VoIPmonitor only listens on port 5060. If your PBX uses a different port for SIP, you must add it. For example:
+Type=oneshot
-:<code>sipport = 5060,5080</code>
+ExecStart=/usr/sbin/ip link set dev eth0 promisc on
+RemainAfterExit=yes
-;3. Check for a restrictive `filter`:
+[Install]
-:If you have a BPF `filter` configured, ensure it is not accidentally excluding the traffic you want to see. For debugging, try commenting out the `filter` line entirely and restarting the sensor.
+WantedBy=multi-user.target
+</syntaxhighlight>
-== Step 5: Check VoIPmonitor Logs for Errors ==
+<syntaxhighlight lang="bash">
-Finally, VoIPmonitor's own logs are the best source for clues. Check the system log for any error messages generated by the sensor on startup or during operation.
+systemctl daemon-reload
-<pre>
+systemctl enable --now promisc.service
-# For Debian/Ubuntu
+</syntaxhighlight>
-tail -f /var/log/syslog | grep voipmonitor
-# For CentOS/RHEL/AlmaLinux
+'''Method 3: rc.local (Legacy)'''
-tail -f /var/log/messages | grep voipmonitor
-</pre>
+Add to <code>/etc/rc.local</code> before <code>exit 0</code>:
-Look for errors like:
+<syntaxhighlight lang="bash">
-* "pcap_open_live(eth0) error: eth0: No such device" (Wrong interface name)
+/sbin/ip link set dev eth0 promisc on
-* "Permission denied" (The sensor is not running with sufficient privileges)
+</syntaxhighlight>
-* Errors related to database connectivity.
-* Messages about dropping packets.
+== Verification ==
+After enabling, verify traffic is visible:
+<syntaxhighlight lang="bash">
+# Quick test with tcpdump
+sudo tcpdump -i eth0 -c 10 "port 5060"
+# More detailed with tshark
+tshark -i eth0 -Y "sip || rtp" -n -c 20
+</syntaxhighlight>
+If you see SIP/RTP packets, promiscuous mode is working correctly.
+== Troubleshooting ==
+{| class="wikitable"
+|-
+! Problem !! Solution
+|-
+| <code>PROMISC</code> flag not showing after enable || Check if interface exists: <code>ip link show</code>. Verify interface name matches config.
+|-
+| Traffic visible in tcpdump but not in VoIPmonitor || Check <code>interface</code> directive in <code>/etc/voipmonitor.conf</code> matches. See [[Sniffer_troubleshooting]].
+|-
+| Promiscuous mode resets after reboot || Use persistent configuration method above.
+|-
+| "Permission denied" when enabling || Run command as root or with <code>sudo</code>.
+|-
+| No traffic even with promisc enabled || Verify SPAN/mirror configuration on switch. See [[Sniffer_troubleshooting]].
+|}
+{{Warning|Security: Promiscuous mode exposes the interface to all network traffic. Only enable on dedicated monitoring interfaces, not on production servers exposed to untrusted networks.}}
+== See Also ==
+* [[Sniffer_troubleshooting]] - Complete troubleshooting guide for capture issues
+* [[Sniffing_modes]] - Deployment topology guide (SPAN, ERSPAN, tunneling)
+* [[Sniffer_configuration]] - Full configuration reference
 == AI Summary for RAG ==
-'''Summary:''' This document provides a step-by-step troubleshooting guide for when the VoIPmonitor sensor is not capturing any calls. The process is broken down into five logical steps. Step 1 is to verify the service is running correctly using `systemctl status` and `ps`. Step 2 is to use `tshark` to confirm if SIP/RTP traffic is actually arriving at the server's network interface. Step 3 covers network-level issues, including an important distinction between Layer 2 mirroring (SPAN/RSPAN) which requires promiscuous mode, and Layer 3 tunneling (ERSPAN/GRE/TZSP/VXLAN) which does NOT require promiscuous mode because the tunnel packets are addressed to the sensor's IP. Step 4 focuses on checking the `voipmonitor.conf` file for common misconfigurations like the `interface`, `sipport`, or `filter` parameters. Finally, Step 5 instructs the user on how to check the system logs (`syslog` or `messages`) for specific error messages from the sensor.
-'''Keywords:''' troubleshooting, no calls, not sniffing, no data, no CDRs, tshark, wireshark, promiscuous mode, promisc, ifconfig, ip link, SPAN, RSPAN, ERSPAN, GRE, TZSP, VXLAN, port mirroring, voipmonitor.conf, interface, sipport, filter, syslog, logs, permission denied
+'''Summary:''' Promiscuous mode allows a network interface to capture all packets regardless of destination MAC address. It is REQUIRED for Layer 2 mirroring methods (SPAN, RSPAN, hardware TAP) because mirrored packets retain their original MAC addresses. It is NOT required for Layer 3 tunneling methods (ERSPAN, GRE, TZSP, VXLAN) because these encapsulate traffic in packets addressed directly to the sensor's IP. Enable with <code>ip link set dev eth0 promisc on</code>. For persistence, use systemd service, netplan dispatcher, or rc.local. Verify with <code>ip link show eth0</code> looking for PROMISC flag.
+'''Keywords:''' promiscuous mode, promisc, SPAN, RSPAN, port mirroring, network TAP, packet capture, ip link, interface configuration, ERSPAN, GRE, TZSP, VXLAN, Layer 2, Layer 3, MAC address, persistent configuration, systemd, netplan
 '''Key Questions:'''
-* Why is VoIPmonitor not recording any calls?
+* Do I need promiscuous mode for VoIPmonitor?
-* How can I check if VoIP traffic is reaching my sensor server?
+* How do I enable promiscuous mode on Linux?
-* What command can I use to see live SIP traffic on the command line?
+* Does ERSPAN require promiscuous mode?
-* How do I enable promiscuous mode on my network card?
+* How do I make promiscuous mode persistent after reboot?
-* Do I need promiscuous mode for ERSPAN or GRE tunnels?
+* How do I check if promiscuous mode is enabled?
-* Does ERSPAN require promiscuous mode on the receiving interface?
+* Why is VoIPmonitor not seeing SPAN traffic?
-* VoIPmonitor is running but I have no new calls in the GUI, what should I check first?
+* What is the difference between SPAN and ERSPAN for promiscuous mode?
-* Where can I find the log files for the VoIPmonitor sniffer?
-* What are the most common reasons for VoIPmonitor not capturing data?