Skip to content

Commit 05e32fd

Browse files
sebastianziebasebastianzieba
committed
Update README and add requirements.txt
1 parent 7422d2d commit 05e32fd

File tree

2 files changed

+78
-62
lines changed

2 files changed

+78
-62
lines changed

‎README.md‎

Lines changed: 74 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ The agent collects and securely sends metrics to your NodeSniff backend over HTT
1212
- Collects CPU, RAM, disk, network, and OS metrics (extensible via Python plugins)
1313
- Secure HTTPS metric transmission with HMAC authentication
1414
- CLI modes for install, remove, cleanup
15-
- Systemd integration with `/usr/bin/nsagent` symlink for convenience
15+
- Systemd integration with `/usr/bin/nsagent` symlink
16+
- Recommended setup as dedicated unprivileged `nodesniff` user
1617

1718
---
1819

@@ -21,7 +22,10 @@ The agent collects and securely sends metrics to your NodeSniff backend over HTT
2122
- Python 3.7+
2223
- Linux (x86, ARM, etc.)
2324
- Python packages:
24-
- `psutil`, `PyYAML`, `requests`
25+
- `psutil`
26+
- `PyYAML`
27+
- `requests`
28+
- `setuptools` (required for some plugin systems)
2529

2630
Install dependencies:
2731
```sh
@@ -30,108 +34,119 @@ pip install -r requirements.txt
3034

3135
---
3236

33-
## Installation
37+
## Installation and Registration (as dedicated user)
3438

35-
1. **Copy the agent to your server:**
36-
```sh
37-
scp nsagent.py user@your-server:/path/
38-
```
39+
### 1. Create dedicated system user
3940

40-
2. **Run the agent for initial setup:**
41-
```sh
42-
sudo python3 ./nsagent.py
43-
```
41+
```bash
42+
sudo useradd --system --no-create-home --shell /usr/sbin/nologin nodesniff
43+
```
44+
45+
### 2. Register the agent (as root)
46+
47+
```bash
48+
sudo ./nsagent.py
49+
```
50+
51+
If Python or packages are missing:
52+
```bash
53+
sudo apt install python3-pip
54+
pip3 install -r requirements.txt
55+
# or, for Raspberry Pi and similar:
56+
sudo pip3 install --break-system-packages PyYAML
57+
```
58+
59+
Paste your company key into:
60+
```bash
61+
sudo nano /etc/nodesniff/nsagent.token
62+
```
63+
64+
Run agent again:
65+
```bash
66+
sudo ./nsagent.py
67+
```
4468

45-
- Creates `/etc/nodesniff/` with placeholder config and token.
46-
- Paste your company key into `/etc/nodesniff/nsagent.token`.
47-
- Re-run the agent:
48-
```sh
49-
sudo ./nsagent.py
50-
```
69+
### 3. Set ownership for runtime directories
5170

52-
- Expected output:
53-
```
54-
[OK] Registration successful.
55-
[OK] 📤 Metrics sent successfully.
56-
```
71+
```bash
72+
sudo chown -R nodesniff:nodesniff /etc/nodesniff
73+
sudo chown -R nodesniff:nodesniff /usr/lib/nodesniff
74+
sudo chown nodesniff:nodesniff /var/log/nsagent.log
75+
```
76+
*(Skip last one if file doesn't exist — it will be created.)*
5777

58-
3. **Install as a systemd service:**
59-
```sh
60-
sudo ./nsagent.py --service
61-
```
78+
### 4. Install and enable the systemd service
79+
80+
```bash
81+
sudo ./nsagent.py --service
82+
sudo systemctl daemon-reload
83+
sudo systemctl restart nodesniff-agent
84+
sudo systemctl enable nodesniff-agent
85+
```
6286

63-
- Requires a successful registration.
64-
- Installs `nodesniff-agent` systemd service and enables it on boot.
65-
- Adds `/usr/bin/nsagent` CLI symlink.
87+
Agent will now run as `nodesniff` user.
88+
89+
### 5. Confirm it's working
90+
91+
```bash
92+
ps aux | grep nsagent
93+
systemctl status nodesniff-agent
94+
```
95+
96+
You should see `User=nodesniff`.
6697

6798
---
6899

69100
## CLI Modes
70101

71102
- `sudo ./nsagent.py`
72-
Standard agent run. Registers (if needed) and enters metric loop.
103+
One-time run (registers if needed, then loops)
73104

74105
- `sudo ./nsagent.py --service`
75-
Installs as a systemd service (requires registration).
106+
Installs systemd service (requires registration)
76107

77108
- `sudo ./nsagent.py --clean`
78-
Full cleanup:
79-
- Stops and disables service
80-
- Removes config, token, logs, metrics
81-
- Deletes `/usr/bin/nsagent` symlink
109+
Uninstalls: removes configs, service, logs, symlink
82110

83111
---
84112

85-
## Re-registration (after removal in dashboard)
86-
87-
If the server is deleted from the NodeSniff dashboard, the agent will detect this (`403 Forbidden`).
88-
To re-register:
89-
90-
1. Run:
91-
```sh
92-
sudo ./nsagent.py
93-
```
94-
95-
2. Re-paste your company key if prompted.
113+
## Re-registration (after dashboard deletion)
96114

97-
3. Re-install the service:
98-
```sh
99-
sudo ./nsagent.py --service
100-
```
115+
```bash
116+
sudo ./nsagent.py
117+
# Paste company key again if prompted
118+
sudo ./nsagent.py --service
119+
```
101120

102121
---
103122

104123
## Updating the Agent
105124

106-
After downloading a new version:
107-
108-
```sh
125+
```bash
109126
sudo ./nsagent.py --clean
110127
# Copy updated nsagent.py
111-
sudo python3 ./nsagent.py
128+
sudo ./nsagent.py
112129
sudo ./nsagent.py --service
113130
```
114131

115132
---
116133

117134
## Uninstall
118135

119-
```sh
136+
```bash
120137
sudo ./nsagent.py --clean
121138
```
122139

123-
Completely removes the agent: service, configs, logs, symlink.
124-
125140
---
126141

127142
## License
128143

129144
GPL v3 — **non-commercial use only**.
130-
For commercial use or support, contact us at [info@nodesniff.com](mailto:info@nodesniff.com).
145+
For commercial use or support, contact us: [info@nodesniff.com](mailto:info@nodesniff.com)
131146

132147
---
133148

134149
## Contact
135150

136151
📧 info@nodesniff.com
137-
🌐 https://www.nodesniff.com
152+
🌐 https://www.nodesniff.com

‎requirements.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1-
psutil>=5.9.0
2-
PyYAML>=6.0
3-
requests>=2.25.0
1+
psutil
2+
PyYAML
3+
requests
4+
setuptools

0 commit comments

Comments
 (0)