NodeSniff Agent

NodeSniff Agent is a lightweight server metrics collector for the NodeSniff monitoring system.
The agent collects and securely sends metrics to your NodeSniff backend over HTTPS.

License: GNU GPL v3 (non-commercial use only)

---

Features

• Collects CPU, RAM, disk, network, and OS metrics (extensible via Python plugins)
• Secure HTTPS metric transmission with HMAC authentication
• CLI modes for install, remove, cleanup
• Systemd integration with /usr/bin/nsagent symlink
• Recommended setup as dedicated unprivileged nodesniff user

---

Requirements

• Python 3.7+
• Linux (x86, ARM, etc.)
• Python packages:
  • psutil
  • PyYAML
  • requests
  • setuptools (required for some plugin systems)

Install dependencies:

pip install -r requirements.txt

---

Installation and Registration (as dedicated user)

1. Create dedicated system user

sudo useradd --system --no-create-home --shell /usr/sbin/nologin nodesniff

2. Register the agent (as root)

sudo ./nsagent.py

If Python or packages are missing:

sudo apt install python3-pip
sudo pip3 install -r requirements.txt
# or, for Raspberry Pi and similar:
sudo pip3 install --break-system-packages PyYAML

Paste your company key into:

sudo nano /etc/nodesniff/nsagent.token

Run agent again:

sudo ./nsagent.py

---

3. Set ownership for runtime directories

sudo mkdir -p /var/log/nodesniff
sudo chown -R nodesniff:nodesniff /etc/nodesniff
sudo chown -R nodesniff:nodesniff /usr/lib/nodesniff
sudo chown -R nodesniff:nodesniff /var/log/nodesniff
sudo chmod 750 /var/log/nodesniff

(Skip file creation — /var/log/nodesniff/nsagent.log will be created automatically.)

---

4. Install and enable the systemd service

sudo ./nsagent.py --service
sudo systemctl daemon-reload
sudo systemctl restart nodesniff-agent
sudo systemctl enable nodesniff-agent

Agent will now run as nodesniff user.

---

5. Confirm it's working

ps aux | grep nsagent
systemctl status nodesniff-agent

You should see:

User=nodesniff
Active: active (running)

---

CLI Modes

• sudo ./nsagent.py
  One-time run (registers if needed, then loops)

• sudo ./nsagent.py --service
  Installs systemd service (requires registration)

• sudo ./nsagent.py --clean
  Uninstalls: removes configs, service, logs, symlink

---

Re-registration (after dashboard deletion)

sudo ./nsagent.py
# Paste company key again if prompted
sudo ./nsagent.py --service

---

Updating the Agent

sudo ./nsagent.py --clean
# Copy updated nsagent.py
sudo ./nsagent.py
sudo ./nsagent.py --service

---

Uninstall

sudo ./nsagent.py --clean

---

Troubleshooting

Permission denied: /var/log/nodesniff/nsagent.log

Create and fix permissions manually:

sudo mkdir -p /var/log/nodesniff
sudo touch /var/log/nodesniff/nsagent.log
sudo chown nodesniff:nodesniff /var/log/nodesniff /var/log/nodesniff/nsagent.log
sudo chmod 750 /var/log/nodesniff
sudo chmod 640 /var/log/nodesniff/nsagent.log
sudo systemctl restart nodesniff-agent

---

Agent not starting (exit-code 1)

Check logs:

journalctl -u nodesniff-agent -n 50 --no-pager

Common causes:

• Missing or placeholder token file /etc/nodesniff/nsagent.token
• Wrong permissions on /etc/nodesniff or /var/log/nodesniff
• Outdated Python version
• Backend or database unavailable

---

Check which user the agent runs as

systemctl show -p User nodesniff-agent.service

Expected:

User=nodesniff

---

Manual test run

sudo -u nodesniff python3 /usr/lib/nodesniff/nsagent.py --daemon

---

License

GPL v3 — non-commercial use only.
For commercial use or support, contact us: info@nodesniff.com

---

Contact

📧 info@nodesniff.com
🌐 https://www.nodesniff.com