Systemd for voipmonitor service management: Difference between revisions

From VoIPmonitor.org
(Add section about watchdog integration with systemd)
(Rewrite: konsolidace a vylepšení struktury - zjednodušeno z 384 na 177 řádků)
 
(3 intermediate revisions by the same user not shown)
Line 3: Line 3:
[[Category:Installation]]
[[Category:Installation]]


'''This guide provides the recommended method for managing the VoIPmonitor sensor service using systemd on modern Linux distributions.'''
'''This guide covers managing the VoIPmonitor sensor service using systemd on modern Linux distributions.'''


== Overview ==
{{Warning|1='''Always use <code>systemctl</code> commands.''' Do not use the legacy <code>service</code> command as systemd may lose track of the process state.}}
 
Modern Linux distributions (Debian, Ubuntu, CentOS, RHEL, AlmaLinux) use systemd as the primary service manager. The recommended approach is to create a systemd unit file that wraps the reliable <code>/etc/init.d/voipmonitor</code> script, ensuring compatibility across various distributions.
 
{{Warning|1='''Always use <code>systemctl</code> commands to manage the service.''' Do not use the legacy <code>service</code> command (e.g., <code>service voipmonitor start</code>) as systemd may lose track of the process state.}}


== Unit File Configuration ==
== Unit File Configuration ==


Create file <code>/etc/systemd/system/voipmonitor.service</code>:
Create <code>/etc/systemd/system/voipmonitor.service</code>:


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
[Unit]
[Unit]
Description=VoIPmonitor sniffer
Description=VoIPmonitor sniffer
After=syslog.target
After=syslog.target network.target
After=network.target
# Add mysql.service only if DB is local (see Dependencies below)
After=mysql.service


[Service]
[Service]
Type=forking
Type=forking
Restart=no
RemainAfterExit=yes
TimeoutSec=5min
TimeoutSec=5min
IgnoreSIGPIPE=no
KillMode=process
KillMode=process
GuessMainPID=no
GuessMainPID=no
RemainAfterExit=yes
IgnoreSIGPIPE=no
SuccessExitStatus=5 6
SuccessExitStatus=5 6
ExecStart=/etc/init.d/voipmonitor start
ExecStart=/etc/init.d/voipmonitor start
Line 39: Line 33:
</syntaxhighlight>
</syntaxhighlight>


== Dependency Customization ==
=== Dependencies ===


<kroki lang="mermaid">
{| class="wikitable"
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
|-
flowchart LR
! Scenario !! Add to [Unit] section
    subgraph "Dependencies"
|-
        A[syslog.target]
| '''Local MySQL/MariaDB''' || <code>After=mysql.service</code>
        B[network.target]
|-
        C[mysql.service]
| '''Napatech SmartNIC''' || <code>After=ntservice.service</code><br/><code>Requires=ntservice.service</code><br/><code>Wants=network-pre.target</code><br/><code>Before=network-pre.target</code>
        D[ntservice.service]
|}
    end
 
    E[voipmonitor.service]
 
    A --> E
    B --> E
    C -.->|"Local DB only"| E
    D -.->|"Napatech only"| E
</kroki>
 
=== MySQL/MariaDB ===
 
The line <code>After=mysql.service</code> is only required if the database is installed locally on the same server. If your database runs on a remote server, you can remove this line.
 
=== Napatech Cards ===
 
If you use Napatech hardware acceleration cards, add the following lines to the <code>[Unit]</code> section to ensure drivers load before VoIPmonitor starts:
 
<syntaxhighlight lang="ini">
Before=network-pre.target
Wants=network-pre.target
After=ntservice.service
Requires=ntservice.service
</syntaxhighlight>
 
== Activation and Management ==


=== Reload systemd after changes ===
== Basic Commands ==


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# After any unit file changes
systemctl daemon-reload
systemctl daemon-reload
</syntaxhighlight>
=== Enable start on boot ===


<syntaxhighlight lang="bash">
# Enable auto-start on boot
systemctl enable voipmonitor
systemctl enable voipmonitor
</syntaxhighlight>
=== Standard management commands ===


<syntaxhighlight lang="bash">
# Start/Stop/Restart
# Start the service
systemctl start voipmonitor
systemctl start voipmonitor
# Stop the service
systemctl stop voipmonitor
systemctl stop voipmonitor
# Restart the service
systemctl restart voipmonitor
systemctl restart voipmonitor


# Check status and view recent logs
# Check status
systemctl status voipmonitor
systemctl status voipmonitor
</syntaxhighlight>
</syntaxhighlight>


== Troubleshooting ==
== Watchdog Integration ==
 
When using the internal watchdog with systemd, configure it to restart via systemctl. Otherwise, systemd will incorrectly report the service as "failed" after a watchdog-triggered restart.
 
Add to <code>/etc/voipmonitor.conf</code>:


=== Service Not Starting vs Connection Failures ===
<syntaxhighlight lang="ini">
watchdog = yes
watchdog_run_command = systemctl restart voipmonitor
</syntaxhighlight>


Before troubleshooting systemd issues, identify whether the problem is with the systemd service OR with network connectivity:
== Controlling Verbose Output ==


{| class="wikitable"
By default, VoIPmonitor outputs statistics to syslog every 10 seconds (controlled by <code>-v 1</code> in the init.d script).
|-
! Problem Type !! Symptoms !! Solution
|-
| '''Service fails to start''' || <code>systemctl start voipmonitor</code> returns error, service shows <code>failed</code> status || Continue with this guide
|-
| '''Service starts but cannot connect''' || Service shows <code>active (running)</code> but logs show "cannot connect to server" || See [[Sniffer_distributed_architecture#Troubleshooting_Connection_Failures|Distributed Architecture Troubleshooting]]
|}


=== Unit File Syntax Errors ===
=== Option 1: Redirect to Dedicated Log (Recommended) ===


If you encounter errors like:
Add to <code>/etc/rsyslog.conf</code>:


<syntaxhighlight lang="text">
<syntaxhighlight lang="rsyslog">
Error: Assignment outside of section. Ignoring.
if $programname == 'voipmonitor' then /var/log/voipmonitor.log
Job for voipmonitor.service failed because the control process exited with error code.
& ~
</syntaxhighlight>
</syntaxhighlight>


This indicates syntax errors in the unit file. To bypass and fix:
Then: <code>systemctl restart rsyslog</code>


<syntaxhighlight lang="bash">
=== Option 2: Disable Statistics Entirely ===
# 1. Identify existing processes
ps aux | grep voipmonitor


# 2. Kill the watchdog process first (find its PID from ps output)
{{Warning|This removes valuable diagnostic metrics. Only use if necessary.}}
kill <PID_WATCHDOG>


# 3. Kill the main voipmonitor process
Edit <code>/etc/init.d/voipmonitor</code>, find the <code>ARGS=</code> line, and remove <code>-v 1</code> (or <code>v 1</code>):
kill -9 <PID_VOIPMONITOR>


# 4. Stop using init.d script
<syntaxhighlight lang="text">
/etc/init.d/voipmonitor stop
# Before:
ARGS="-v 1 --config-file /etc/voipmonitor.conf"


# 5. Start using init.d script (bypasses broken systemd unit)
# After:
/etc/init.d/voipmonitor start
ARGS="--config-file /etc/voipmonitor.conf"
</syntaxhighlight>
</syntaxhighlight>


=== Common Unit File Errors ===
Then: <code>systemctl daemon-reload && systemctl restart voipmonitor</code>
 
== Troubleshooting ==
 
=== Unit File Syntax Errors ===


* Missing <code>[Unit]</code>, <code>[Service]</code>, or <code>[Install]</code> section headers
'''Symptom:''' "Assignment outside of section" or "control process exited with error code"
* Assignments placed outside of their proper sections
* Typos in directive names (e.g., <code>ExecStar</code> instead of <code>ExecStart</code>)
* Missing equals (<code>=</code>) signs between directive and value


After fixing the unit file:
'''Fix:''' Check unit file for:
* Missing section headers (<code>[Unit]</code>, <code>[Service]</code>, <code>[Install]</code>)
* Typos in directive names
* Missing <code>=</code> signs


'''Emergency bypass:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
systemctl daemon-reload
killall -9 voipmonitor
systemctl start voipmonitor
/etc/init.d/voipmonitor start
# Fix unit file, then:
systemctl daemon-reload && systemctl start voipmonitor
</syntaxhighlight>
</syntaxhighlight>


== Internal Watchdog and SystemD ==
=== Multiple Instances Running (Duplicate Packets, Corrupted RRD) ===


When using SystemD to manage the VoIPmonitor service, there is a potential issue if the internal watchdog restarts the VoIPmonitor process. By default, the internal watchdog may attempt to restart the binary directly. When this happens, the main process ID (PID) tracked by SystemD exits, causing SystemD to mark the service as "failed" or "dead," even though a new process has been spawned.
'''Symptom:''' Duplicate SIP packets in GUI, broken RRD graphs, multiple voipmonitor processes


{{Warning|If the internal watchdog is enabled but not configured to use SystemD for restarts, the SystemD service status will incorrectly show the service as failed after a watchdog-triggered restart.}}
'''Cause:''' Both systemd unit and init.d wrapper trying to start VoIPmonitor


=== Configuring the Watchdog to Use SystemD ===
'''Fix:'''


To ensure that SystemD correctly tracks the service status after a watchdog-triggered restart, edit the <code>/etc/voipmonitor.conf</code> file:
<syntaxhighlight lang="bash">
# 1. Kill all instances
sudo killall -9 voipmonitor


<ol>
# 2. Disable init.d wrapper (keeps script but prevents auto-start)
<li>Enable the watchdog (if not already enabled):
sudo chmod -x /etc/init.d/voipmonitor


<syntaxhighlight lang="ini">
# 3. Delete corrupted RRD files
watchdog = yes
sudo rm -f /var/spool/voipmonitor/rrd/*
</syntaxhighlight>


</li>
# 4. Start via systemd
<li>Add the following line to make the watchdog use SystemD for restarts:
sudo systemctl enable voipmonitor
sudo systemctl start voipmonitor


<syntaxhighlight lang="ini">
# 5. Verify single instance
watchdog_run_command = systemctl restart voipmonitor
ps aux | grep "[v]oipmonitor"
</syntaxhighlight>
</syntaxhighlight>


</li>
{{Note|1=The <code>chmod -x</code> disables the SysV compatibility service that systemd auto-generates from init.d scripts.}}
</ol>
 
=== Why This Works ===
 
Setting <code>watchdog_run_command</code> forces the watchdog to hand over the restart process to SystemD via <code>systemctl restart</code>. This ensures that SystemD manages the entire stop/start cycle, keeps its internal state tracking consistent, and correctly reports the service as <code>active (running)</code> after a watchdog-triggered restart.


=== Verification ===
=== Connection Failures (Service Running but Not Connecting) ===


After configuration, you can verify that SystemD correctly tracks the service:
If <code>systemctl status voipmonitor</code> shows "active (running)" but logs show connection errors, the problem is not systemd-related. See [[Sniffer_distributed_architecture#Troubleshooting|Distributed Architecture Troubleshooting]].


<syntaxhighlight lang="bash">
== See Also ==
# Check service status
systemctl status voipmonitor


# Service should show "active (running)" not "failed" or "dead"
* [[Sniffer_configuration]] - Full configuration reference
</syntaxhighlight>
* [[Sniffer_installation]] - Installation guide
* [[Multiple_sniffer_instancies]] - Running multiple sensors on one host


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' This guide provides the stable method for managing the VoIPmonitor sensor using systemd by wrapping the legacy init.d script in a unit file. This approach ensures compatibility across various distributions including AlmaLinux 9.5. The unit file configuration uses <code>Type=forking</code> with <code>RemainAfterExit=yes</code> and calls <code>/etc/init.d/voipmonitor start/stop</code> directly. Key dependencies include <code>After=mysql.service</code> for local databases and <code>After=ntservice.service</code> with <code>Requires=ntservice.service</code> for Napatech hardware. The guide emphasizes using <code>systemctl</code> commands exclusively (never the legacy <code>service</code> command) for reliable process tracking. A critical configuration for watchdog integration is setting <code>watchdog = yes</code> and <code>watchdog_run_command = systemctl restart voipmonitor</code> in <code>/etc/voipmonitor.conf</code> to prevent systemd from incorrectly reporting the service as failed after a watchdog-triggered restart. Troubleshooting covers distinguishing between systemd failures and network connectivity issues, and provides steps to bypass a faulty unit file using the init.d script directly.
'''Summary:''' Guide for managing VoIPmonitor sensor with systemd. Create unit file at <code>/etc/systemd/system/voipmonitor.service</code> with <code>Type=forking</code> and <code>RemainAfterExit=yes</code>. Key dependencies: add <code>After=mysql.service</code> for local DB only, add <code>After=ntservice.service</code> with <code>Requires=ntservice.service</code> for Napatech cards. Always use <code>systemctl</code> commands (not legacy <code>service</code>). For watchdog integration, set <code>watchdog_run_command = systemctl restart voipmonitor</code> to prevent systemd from showing failed status after watchdog restarts. For multiple instance conflicts (duplicate packets, corrupted RRD), run <code>chmod -x /etc/init.d/voipmonitor</code> to disable the init.d wrapper, delete RRD files, and restart via systemd. For verbose log spam (every 10 seconds), either redirect via rsyslog or remove <code>-v 1</code> from the init.d ARGS line.


'''Keywords:''' systemd, systemctl, voipmonitor.service, init.d wrapper, unit file, Type=forking, RemainAfterExit, dependency, After=mysql.service, Napatech, AlmaLinux, service management, daemon-reload, enable on boot, watchdog, watchdog_run_command, restart automation, process tracking
'''Keywords:''' systemd, systemctl, voipmonitor.service, unit file, Type=forking, RemainAfterExit, After=mysql.service, Napatech, ntservice, daemon-reload, watchdog, watchdog_run_command, multiple instances, duplicate packets, corrupted RRD, chmod -x, verbose output, syslog spam, -v 1, rsyslog


'''Key Questions:'''
'''Key Questions:'''
* What is the recommended systemd configuration for VoIPmonitor?
* What is the recommended systemd unit file for VoIPmonitor?
* Why should I avoid the <code>service</code> command and use <code>systemctl</code>?
* How do I configure systemd dependencies for MySQL and Napatech?
* How do I configure systemd to wait for MySQL before starting VoIPmonitor?
* How do I ensure Napatech drivers are loaded before the sniffer starts?
* What is the correct content of /etc/systemd/system/voipmonitor.service?
* How do I make VoIPmonitor start automatically on boot?
* How do I make VoIPmonitor start automatically on boot?
* How do I bypass a broken systemd unit file and start VoIPmonitor manually?
* Why does systemd show service as failed after watchdog restart?
* What causes "Assignment outside of section" error in systemd?
* How do I fix multiple voipmonitor processes running (duplicate packets, corrupted RRD)?
* How do I troubleshoot VoIPmonitor service startup failures?
* How do I stop init.d and systemd from conflicting?
* How does the internal watchdog interact with systemd service management?
* How do I disable or redirect the verbose statistics output to syslog?
* Why does systemd incorrectly show the service as failed after a watchdog restart?
* What should I set <code>watchdog_run_command</code> to when using systemd?
* How do I ensure systemd correctly tracks the VoIPmonitor service after watchdog restarts?

Latest revision as of 16:48, 8 January 2026


This guide covers managing the VoIPmonitor sensor service using systemd on modern Linux distributions.

⚠️ Warning: Always use systemctl commands. Do not use the legacy service command as systemd may lose track of the process state.

Unit File Configuration

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

[Unit]
Description=VoIPmonitor sniffer
After=syslog.target network.target
# Add mysql.service only if DB is local (see Dependencies below)

[Service]
Type=forking
RemainAfterExit=yes
TimeoutSec=5min
KillMode=process
GuessMainPID=no
IgnoreSIGPIPE=no
SuccessExitStatus=5 6
ExecStart=/etc/init.d/voipmonitor start
ExecStop=/etc/init.d/voipmonitor stop
PrivateTmp=false

[Install]
WantedBy=multi-user.target

Dependencies

Scenario Add to [Unit] section
Local MySQL/MariaDB After=mysql.service
Napatech SmartNIC After=ntservice.service
Requires=ntservice.service
Wants=network-pre.target
Before=network-pre.target

Basic Commands

# After any unit file changes
systemctl daemon-reload

# Enable auto-start on boot
systemctl enable voipmonitor

# Start/Stop/Restart
systemctl start voipmonitor
systemctl stop voipmonitor
systemctl restart voipmonitor

# Check status
systemctl status voipmonitor

Watchdog Integration

When using the internal watchdog with systemd, configure it to restart via systemctl. Otherwise, systemd will incorrectly report the service as "failed" after a watchdog-triggered restart.

Add to /etc/voipmonitor.conf: 

watchdog = yes
watchdog_run_command = systemctl restart voipmonitor

Controlling Verbose Output

By default, VoIPmonitor outputs statistics to syslog every 10 seconds (controlled by -v 1 in the init.d script).

Option 1: Redirect to Dedicated Log (Recommended)

Add to /etc/rsyslog.conf: 

if $programname == 'voipmonitor' then /var/log/voipmonitor.log
& ~

Then: systemctl restart rsyslog

Option 2: Disable Statistics Entirely

⚠️ Warning: This removes valuable diagnostic metrics. Only use if necessary.

Edit /etc/init.d/voipmonitor, find the ARGS= line, and remove -v 1 (or v 1): 

# Before:
ARGS="-v 1 --config-file /etc/voipmonitor.conf"

# After:
ARGS="--config-file /etc/voipmonitor.conf"

Then: systemctl daemon-reload && systemctl restart voipmonitor

Troubleshooting

Unit File Syntax Errors

Symptom: "Assignment outside of section" or "control process exited with error code"

Fix: Check unit file for:

  • Missing section headers ([Unit], [Service], [Install])
  • Typos in directive names
  • Missing = signs

Emergency bypass: 

killall -9 voipmonitor
/etc/init.d/voipmonitor start
# Fix unit file, then:
systemctl daemon-reload && systemctl start voipmonitor

Multiple Instances Running (Duplicate Packets, Corrupted RRD)

Symptom: Duplicate SIP packets in GUI, broken RRD graphs, multiple voipmonitor processes

Cause: Both systemd unit and init.d wrapper trying to start VoIPmonitor

Fix: 

# 1. Kill all instances
sudo killall -9 voipmonitor

# 2. Disable init.d wrapper (keeps script but prevents auto-start)
sudo chmod -x /etc/init.d/voipmonitor

# 3. Delete corrupted RRD files
sudo rm -f /var/spool/voipmonitor/rrd/*

# 4. Start via systemd
sudo systemctl enable voipmonitor
sudo systemctl start voipmonitor

# 5. Verify single instance
ps aux | grep "[v]oipmonitor"

ℹ️ Note: The chmod -x disables the SysV compatibility service that systemd auto-generates from init.d scripts.

Connection Failures (Service Running but Not Connecting)

If systemctl status voipmonitor shows "active (running)" but logs show connection errors, the problem is not systemd-related. See Distributed Architecture Troubleshooting.

See Also

AI Summary for RAG

Summary: Guide for managing VoIPmonitor sensor with systemd. Create unit file at /etc/systemd/system/voipmonitor.service with Type=forking and RemainAfterExit=yes. Key dependencies: add After=mysql.service for local DB only, add After=ntservice.service with Requires=ntservice.service for Napatech cards. Always use systemctl commands (not legacy service). For watchdog integration, set watchdog_run_command = systemctl restart voipmonitor to prevent systemd from showing failed status after watchdog restarts. For multiple instance conflicts (duplicate packets, corrupted RRD), run chmod -x /etc/init.d/voipmonitor to disable the init.d wrapper, delete RRD files, and restart via systemd. For verbose log spam (every 10 seconds), either redirect via rsyslog or remove -v 1 from the init.d ARGS line.

Keywords: systemd, systemctl, voipmonitor.service, unit file, Type=forking, RemainAfterExit, After=mysql.service, Napatech, ntservice, daemon-reload, watchdog, watchdog_run_command, multiple instances, duplicate packets, corrupted RRD, chmod -x, verbose output, syslog spam, -v 1, rsyslog

Key Questions:

  • What is the recommended systemd unit file for VoIPmonitor?
  • How do I configure systemd dependencies for MySQL and Napatech?
  • How do I make VoIPmonitor start automatically on boot?
  • Why does systemd show service as failed after watchdog restart?
  • How do I fix multiple voipmonitor processes running (duplicate packets, corrupted RRD)?
  • How do I stop init.d and systemd from conflicting?
  • How do I disable or redirect the verbose statistics output to syslog?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Systemd_for_voipmonitor_service_management&oldid=10084"