SNMP Trap Receiver Service

The SNMP trap receiver listens for traps from your network devices and hands them to rConfig, so a “configuration changed” trap can trigger a backup, a filter or a notification within seconds. From V8.4.1 it runs as the systemd service rconfig-snmptrap, as the web server user, and you manage it with php artisan rconfig:snmp-trap-service. This page covers installing it, upgrading an older install that ran it under Supervisor, checking it works, and fixing it when it doesn’t.

To build filters and read received traps in the UI, see SNMP Traps UI and Administration. For background on how traps fit with backups and Change Pulse, see SNMP Traps Concepts.

---

How the trap receiver runs

	V8.4.1 and later
Service	rconfig-snmptrap (/etc/systemd/system/rconfig-snmptrap.service)
Runs as	The web server user: apache on RHEL, Rocky, Alma, Oracle, CentOS and Amazon Linux, www-data on Ubuntu and Debian
Port	UDP 162 by default, bound through the CAP_NET_BIND_SERVICE capability, so it never needs root, a firewall redirect or a high port
Restarts	Restart=always, 5 seconds after it stops for any reason
Logs	The systemd journal: journalctl -u rconfig-snmptrap
Community string and SNMPv3 users	Network Services > SNMP Traps > Settings in the UI, never on the command line

Earlier versions ran the receiver as root under Supervisor, as the rconfig-snmp-trap program, with the community string on its command line. If your server still has that setup, follow Upgrading from an earlier version.

The unit file starts with # Managed by rConfig (php artisan rconfig:snmp-trap-service install). Local edits are overwritten. Don’t edit it by hand. To change a setting, run the install again with the new option (see Change a setting).

Bare metal installs only

The receiver service is for rConfig installed directly on a server. rconfig:snmp-trap-service has no Docker handling, so don’t run it inside the rConfig container. The Worker Privilege check also skips the receiver in Docker.

---

Prerequisites

• Shell access to the rConfig server with sudo. Installing, restarting and removing the service all need root.

• The PHP SNMP extension. Without it the receiver exits with SNMP extension is not loaded. Please install php-snmp extension. and systemd restarts it every 5 seconds.

  php -m | grep -E 'snmp|sockets'
  
  sudo dnf install php-snmp        # RHEL, Rocky, Alma
  sudo apt-get install php-snmp    # Ubuntu, Debian

• UDP 162 open in the server firewall:

  # RHEL, Rocky, Alma (firewalld)
  sudo firewall-cmd --add-port=162/udp --permanent
  sudo firewall-cmd --reload
  
  # Ubuntu (UFW)
  sudo ufw allow 162/udp

• Network devices set to send traps to the rConfig server. For example, on Cisco IOS:

  snmp-server host <rconfig-server-ip> traps version 2c <community>
  snmp-server enable traps config
  snmp-server enable traps syslog

• Only one rConfig install per server can run the receiver, because only one process can listen on the port. See Two rConfig installs on one server.

---

Systemd service

Install the receiver

Run the install as root from the rConfig folder:

cd /var/www/html/rconfig8/current
sudo php artisan rconfig:snmp-trap-service install

With no options it listens on 0.0.0.0, port 162. The install:

1. Checks that the web server user exists and isn’t root.
2. Writes /etc/systemd/system/rconfig-snmptrap.service as a root:root 0644 file with User= set to the web server user, and runs restorecon on it where SELinux tools are installed.
3. Reloads systemd, then enables and starts the service.

A successful run ends with:

Installed /etc/systemd/system/rconfig-snmptrap.service (runs as apache).
✅ SNMP trap receiver running on 0.0.0.0:162 as apache.

If the service is written but won’t start, the install prints ❕ The service was installed but could not be started. Check: journalctl -u rconfig-snmptrap.service and exits with code 1. See The service won’t start.

Run sudo php artisan rconfig:snmp-trap-service with no action to choose from a menu instead (“SNMP trap receiver: what would you like to do?”).

Set the community string and SNMPv3 users

Open Network Services > SNMP Traps and go to the Settings tab:

• The Trap Receiver card holds the Community String, Require Community and Accept SNMPv3.
• The SNMPv3 Users card holds the v3 users your devices send as.

The receiver reads these settings itself, so you don’t restart it after a change. For each field, see Settings: receiver and SNMPv3 users.

--community still exists on the install command but is deprecated. It only fills in the community setting when none is stored, and is never written to the service file, so the community string no longer shows in ps.

Options

Option	Default	Valid values
--host=	0.0.0.0	An IP address. Use a single interface address to listen on that interface only.
--port=	162	1 to 65535
--timeout=	5	1 to 300 seconds
--memory-limit=	512	64 to 4096 MB
--community=	none	Deprecated. Fills the community setting only when it is empty.
--if-installed		Used by the deploy script. Updates a receiver that is already installed and does nothing otherwise.
--force		Uninstall without asking.

A value outside these ranges stops the install with the reason and Nothing was changed.

Change a setting

Run the install again with only the options you want to change. Every other setting keeps its current value from the service file:

# Listen on the management interface only
sudo php artisan rconfig:snmp-trap-service install --host=192.168.100.10

# More memory for a busy receiver
sudo php artisan rconfig:snmp-trap-service install --memory-limit=1024

If you change the port, update the firewall rule and the trap destination on every device.

Manage the receiver

# Status. Works as any user. Exits 1 if the receiver is not installed or not running.
php artisan rconfig:snmp-trap-service status

# Restart
sudo php artisan rconfig:snmp-trap-service restart

# Stop and remove the service (asks first; add --force to skip the question)
sudo php artisan rconfig:snmp-trap-service uninstall

# The same service through systemd
systemctl status rconfig-snmptrap
journalctl -u rconfig-snmptrap -f

status prints SNMP trap receiver (rconfig-snmptrap.service): active when it is running. When the service is installed but stopped, it adds The service is installed but not running. Start it with: sudo php artisan rconfig:snmp-trap-service restart.

rconfig:snmp-trap-supervisor still works as an alias of rconfig:snmp-trap-service, so older scripts keep working. Its old --user, --base-path and --supervisor-config-dir options are gone.

---

Upgrading from an earlier version

What the deploy does

The rConfig deploy script runs php artisan rconfig:snmp-trap-service install --if-installed as root on every update. On a server where the receiver was set up under Supervisor (an rconfig-snmp-trap program for this install in a folder Supervisor loads), it:

1. Copies the community string from the old Supervisor command line into Network Services > SNMP Traps > Settings, if no community is stored there yet. It prints Copied the community string into Network Services > SNMP Traps > Settings. Manage it there from now on.
2. Writes /etc/systemd/system/rconfig-snmptrap.service with the same host, port, timeout and memory limit. Any value missing from the old command line takes the default.
3. Stops the old rconfig-snmp-trap Supervisor program and removes its config. A symlinked config is removed, never the file it points to.
4. Enables and starts the new service.

Traps sent during the few seconds of the switch are not received. The old program is migrated whether or not it was running at the time.

On later updates, the deploy restarts the service if it is enabled, so every update also misses a few seconds of traps. If nothing is set up for this install, the step prints The SNMP trap receiver is not installed for this rConfig, so there is nothing to update. and moves on.

A problem in this step is a deploy warning, not a failure: the deploy carries on and finishes the update. Read the deploy output for the messages below.

After upgrading

• supervisorctl status no longer lists rconfig-snmp-trap. Check the receiver with systemctl status rconfig-snmptrap or php artisan rconfig:snmp-trap-service status.
• Handler output is in the journal: journalctl -u rconfig-snmptrap. storage/logs/snmp-trap-handler.log is no longer written. The old file is not deleted, so remove it when you no longer need it.
• Update any monitoring or runbooks that checked Supervisor for the trap receiver.
• Manage the community string in the UI. It no longer appears in ps.
• Run sudo php artisan rconfig:check-worker-user. The SNMP trap receiver line should read OK. See Worker Privilege.

Ubuntu: a receiver that never ran

On Ubuntu, Supervisor only loads .conf files from /etc/supervisor/conf.d, so a receiver installed there as snmptrap_supervisor.ini never started. The deploy removes that file and installs the service, but leaves it off:

The SNMP trap receiver is installed but not turned on, because it was not running before this update.
   Turn it on with: sudo php artisan rconfig:snmp-trap-service install

Run that command when you want traps.

If the deploy warns about the receiver

Message	What happened and what to do
❕ Could not stop the old Supervisor program rconfig-snmp-trap: … followed by … was left in place and the new service was not started, so the old receiver keeps the port. and Fix supervisorctl, then run this command again.	The community string was copied and the service file written, but the service is not enabled. The old receiver keeps running. Fix supervisorctl access (try sudo supervisorctl status), then run sudo php artisan rconfig:snmp-trap-service install.
❕ /etc/systemd/system/rconfig-snmptrap.service belongs to another rConfig install on this server. Nothing was changed.	Another rConfig on this server owns the receiver. See Two rConfig installs on one server.
❕ … runs the trap receiver for another rConfig install, so it was left alone. followed by Only one receiver can listen on the port. The service was installed but not started.	An old Supervisor program for a different install still holds the port. Decide which install receives traps, remove the other one’s receiver, then run the install again.
supervisorctl reread/update failed. The old program is stopped, but supervisorctl may list it until Supervisor is restarted.	The new service is running. The old entry disappears the next time Supervisor restarts.

Upgrading from before V8.4.0

If you are jumping from a release before V8.4.0, these changes from 8.4.0 also apply:

• Require Community is off after the upgrade, so v1/v2c traps keep arriving whatever community they carry. Switch it on once all your devices send the stored community.
• SNMPv3 is off until you add a user and switch on Accept SNMPv3.
• The community string is no longer saved with new trap log rows. Older rows keep it until the Data Purge Tool removes them (90 days by default).
• storage/logs/snmp.log and storage/logs/snmp-trap-handler-error.log from before 8.4.0 are no longer written. Delete them if you like.

Two rConfig installs on one server

Only one install can own the rconfig-snmptrap service and the port. On the second install, install, uninstall and the deploy step all refuse with the “belongs to another rConfig install” message, and the Worker Privilege check shows the receiver as skipped. Run the receiver from the install that should get the traps.

---

Check that it works

1. Confirm the service is running as the web server user:

   systemctl status rconfig-snmptrap
   ps -eo user=,cmd= | grep '[s]nmp-trap-handler'

   The ps line starts with apache or www-data, followed by php …/artisan rconfig:snmp-trap-handler --daemon --host=0.0.0.0 --port=162 ….

2. Confirm it is listening. ss needs sudo to show a process owned by another user:

   sudo ss -ulnp | grep :162

3. Send a test trap from the rConfig server, then from a device or another host:

   # Install the SNMP tools if needed
   sudo dnf install net-snmp-utils    # RHEL, Rocky, Alma
   sudo apt-get install snmp          # Ubuntu, Debian
   
   # SNMPv2c
   snmptrap -v2c -c <community> 127.0.0.1:162 "" 1.3.6.1.4.1.9.9.43.2.0.1 \
     1.3.6.1.4.1.9.9.43.1.1.1.0 s "Configuration changed by admin"
   
   # SNMPv1
   snmptrap -v1 -c <community> 127.0.0.1:162 \
     1.3.6.1.4.1.9.9.43 localhost 6 1 "" \
     1.3.6.1.4.1.9.9.43.1.1.1.0 s "Test trap message"
   
   # SNMPv3: add the user under Settings > SNMPv3 Users first and switch on Accept SNMPv3
   snmptrap -v3 -l authPriv -u rconfig-traps \
     -a SHA-256 -A 'auth-password' -x AES -X 'priv-password' \
     127.0.0.1:162 "" 1.3.6.1.6.3.1.1.5.3 \
     1.3.6.1.2.1.2.2.1.1.7 i 7

4. Open Network Services > SNMP Traps and go to the Logs tab. Each test trap appears as a row. If one shows as rejected, the reason under the badge says why (wrong community, wrong v3 password, unknown v3 user or a switched-off SNMP version). See rejected traps.

---

Where trap data and logs go

Location	What it holds	Look here when
Logs tab in the UI (snmp_trap_logs table)	One row per received trap: source IP, OID, varbinds, matched filter, resolved device, status and the actions that ran. Traps that match no filter are kept with status filtered_out. Refused traps get one rejected row per source and reason each minute.	You want to know whether a trap arrived and what rConfig did with it
The journal: journalctl -u rconfig-snmptrap	The receiver process itself: startup, listening address, a health line every 5 minutes, memory warnings, socket errors, restarts and any PHP fatal error.	The receiver won’t start, keeps restarting, or you want to confirm it is alive
storage/logs/snmp-YYYY-MM-DD.log	Processing problems only: packets that couldn’t be parsed, traps with no OID, IP mapping auto-create failures, and a fallback copy of any trap the database couldn’t store. Rotated daily, 14 days kept.	A trap you expected is missing from the Logs tab

A healthy receiver looks like this in the journal:

[2026-10-25 14:00:01] INFO: Starting SNMP Trap Handler...
[2026-10-25 14:00:01] INFO: Listening for SNMP traps on 0.0.0.0:162 (memory limit 512MB)
[2026-10-25 14:05:01] INFO: Health: up 0.08h, 42 traps (504/hour), memory 38MB, peak 40MB

Individual traps are not written to the journal. Use the Logs tab for those. Trap log rows are removed by the Data Purge Tool (snmp_trap_logs, 90 days by default).

Trace trap processing

The daily snmp-*.log only records problems by default. To see every step for each trap (parsing, filter matching, device resolution), raise the log level in .env:

SNMP_LOG_LEVEL=debug
# Optional: days of snmp-*.log files to keep (default 14)
SNMP_LOG_DAYS=14

Then clear the config cache as the web server user, and restart the receiver and Horizon so both pick up the change (www-data on Ubuntu):

cd /var/www/html/rconfig8/current
sudo -u apache php artisan config:clear
sudo php artisan rconfig:snmp-trap-service restart
sudo -u apache php artisan horizon:terminate

Caution

Debug level writes several lines per trap. Set SNMP_LOG_LEVEL back to warning (or remove it) once you’ve finished, especially on a busy receiver.

---

Securing trap reception

Prefer SNMPv3. v1/v2c communities travel in clear text, so anyone on the path can read and replay them. SNMPv3 signs every trap and can encrypt it. Add a user under Settings > SNMPv3 Users, switch on Accept SNMPv3, and once your devices have moved over, switch off v1/v2c in the same tab.

Require the community for v1/v2c. Where devices can only send v2c, store a long, unique community and switch on Require Community. Traps with any other community are then rejected. Generate one with:

openssl rand -base64 24

Listen on one interface. Reinstall with --host set to the management interface address:

sudo php artisan rconfig:snmp-trap-service install --host=192.168.100.10

Accept traps only from known networks. Limit UDP 162 in the firewall to your device ranges. For example, with firewalld:

sudo firewall-cmd --permanent --remove-port=162/udp
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port port="162" protocol="udp" accept'
sudo firewall-cmd --reload

---

Troubleshooting

The service won’t start

systemctl status rconfig-snmptrap
journalctl -u rconfig-snmptrap -n 50

Common causes:

• The PHP SNMP extension is missing. The journal shows SNMP extension is not loaded. Please install php-snmp extension. Install php-snmp (see Prerequisites), then sudo php artisan rconfig:snmp-trap-service restart.

• Something else holds the port. Find it with sudo ss -ulnp | grep :162. A leftover snmptrapd, or an old Supervisor receiver from before 8.4.1, are the usual suspects. Stop it, then restart the service.

• Root-owned files in storage. The receiver runs as the web server user, so it can’t write files that a root process left behind. See Worker Privilege to find what ran as root, then hand the files back:

  cd /var/www/html/rconfig8/current
  sudo find storage bootstrap/cache \( ! -user apache -o ! -group apache \) -exec chown -h apache:apache {} +

  Use www-data on Ubuntu.

• The database or Redis is down. Fix that first. systemd keeps trying every 5 seconds, so the receiver comes back on its own once they are up.

No traps arrive

1. Check the receiver is listening: sudo ss -ulnp | grep :162.
2. Send a trap to 127.0.0.1:162 from the rConfig server. If it arrives but device traps don’t, the firewall or the device is the problem. Check sudo firewall-cmd --list-all (or sudo ufw status) and the device’s trap destination (show running-config | include snmp-server host on Cisco).
3. If the local trap doesn’t arrive either, check the journal for socket errors.
4. Look on the Logs tab for rejected rows and fix the device or the setting named in the reason.

The dashboard or the SNMP page says the receiver is not running as the web user

The SNMP Traps page shows “The receiver is not running as the web user” when the Worker Privilege check finds a problem with the receiver. Usually an old Supervisor config still runs it, or someone started the handler by hand as root. The alert shows the fix to run, which is almost always:

cd /var/www/html/rconfig8/current
sudo php artisan rconfig:snmp-trap-service install

Every message and its fix is listed under SNMP trap receiver on the Worker Privilege page.

Traps stop after securing Redis

rconfig:redis-secure asks the receiver to restart through a Redis cache key, so it picks up the new password without sudo. The receiver checks for the request every 5 seconds, exits with Restart requested; exiting so the service manager relaunches the handler with fresh config., and systemd starts it again 5 seconds later. If traps don’t come back, restart it by hand with sudo php artisan rconfig:snmp-trap-service restart. See Redis Authentication.

Run the handler by hand

To watch traps arrive in the terminal, stop the service, run the handler as the web server user on a free high port, and send test traps to that port. Leave off --daemon, which prints nothing useful to a terminal.

sudo systemctl stop rconfig-snmptrap
cd /var/www/html/rconfig8/current
sudo -u apache php artisan rconfig:snmp-trap-handler --host=127.0.0.1 --port=10162

# In a second terminal
snmptrap -v2c -c <community> 127.0.0.1:10162 "" 1.3.6.1.6.3.1.1.5.1

Each trap prints a block starting === SNMP TRAP RECEIVED ===, with the source, time, SNMP version and the varbinds. A refused trap prints Trap rejected or unparseable - see the SNMP trap logs. Press Ctrl+C when you’re done, then sudo systemctl start rconfig-snmptrap.

Don’t run the handler as root. It still starts, but logs The SNMP trap handler is running as root. Run it as the web user with: sudo php artisan rconfig:snmp-trap-service install and leaves root-owned files behind.

High CPU or memory use

Check the health line in the journal, which shows the trap rate and memory:

journalctl -u rconfig-snmptrap | grep Health | tail -n 5

• A trap storm from one device. Find the source on the Logs tab, block it in the firewall while you fix the device, and remove the block afterwards.
• The receiver needs more memory. Reinstall with a higher limit, for example sudo php artisan rconfig:snmp-trap-service install --memory-limit=1024.

---

What’s next

• SNMP Traps UI and Administration: build trap filters and device resolution mappings, and read the trap logs.
• Worker Privilege: check that the receiver, Horizon and the scheduler all run as the web server user.