https://github.com/nodesniff/nodesniff-linux-agent
NodeSniff agent for collecting system metrics on Linux servers.
https://github.com/nodesniff/nodesniff-linux-agent
agent fasapi linux linux-agent linux-app metrics metrics-collector monitoring nodesniff python servers system-monitoring
Last synced: about 1 month ago
JSON representation
NodeSniff agent for collecting system metrics on Linux servers.
- Host: GitHub
- URL: https://github.com/nodesniff/nodesniff-linux-agent
- Owner: nodesniff
- License: other
- Created: 2025-06-18T07:16:52.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T15:35:13.000Z (2 months ago)
- Last Synced: 2026-03-22T05:54:49.790Z (2 months ago)
- Topics: agent, fasapi, linux, linux-agent, linux-app, metrics, metrics-collector, monitoring, nodesniff, python, servers, system-monitoring
- Language: Python
- Homepage: https://www.nodesniff.com
- Size: 74.2 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```sh
pip install -r requirements.txt
```
---
## Installation and Registration (as dedicated user)
### 1. Create dedicated system user
```bash
sudo useradd --system --no-create-home --shell /usr/sbin/nologin nodesniff
```
### 2. Register the agent (as root)
```bash
sudo ./nsagent.py
```
If Python or packages are missing:
```bash
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:
```bash
sudo nano /etc/nodesniff/nsagent.token
```
Run agent again:
```bash
sudo ./nsagent.py
```
---
### 3. Set ownership for runtime directories
```bash
# Create log directory
sudo mkdir -p /var/log/nodesniff
# Ensure agent user owns all runtime paths
sudo chown -R nodesniff:nodesniff /etc/nodesniff
sudo chown -R nodesniff:nodesniff /usr/lib/nodesniff
sudo chown -R nodesniff:nodesniff /var/log/nodesniff
# Secure permissions
sudo chmod 750 /var/log/nodesniff
# Ensure log file is writable by agent
sudo touch /var/log/nodesniff/nsagent.log
sudo chown nodesniff:nodesniff /var/log/nodesniff/nsagent.log
sudo chmod 640 /var/log/nodesniff/nsagent.log
```
### 4. Install and enable the systemd service
```bash
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
```bash
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)
```bash
sudo ./nsagent.py
# Paste company key again if prompted
sudo ./nsagent.py --service
```
---
## Updating the Agent
```bash
sudo ./nsagent.py --clean
# Copy updated nsagent.py
sudo ./nsagent.py
sudo ./nsagent.py --service
```
---
## Uninstall
```bash
sudo ./nsagent.py --clean
```
---
## Troubleshooting
### Permission denied: `/var/log/nodesniff/nsagent.log`
Create and fix permissions manually:
```bash
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:
```bash
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
```bash
systemctl show -p User nodesniff-agent.service
```
Expected:
```
User=nodesniff
```
---
### Manual test run
```bash
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](mailto:info@nodesniff.com)
---
## Contact
📧 info@nodesniff.com
🌐 https://www.nodesniff.com