update README
This commit is contained in:
Andreas Wrede
@@ -76,7 +76,7 @@ See [docs/NAGIOS_INTEGRATION.md](docs/NAGIOS_INTEGRATION.md) for complete integr
|
||||
### Creating Custom Plugins
|
||||
|
||||
```python
|
||||
from hbd.plugin import MonitorPlugin
|
||||
from hbd.client.plugin import MonitorPlugin
|
||||
|
||||
class DiskMonitorPlugin(MonitorPlugin):
|
||||
name = "disk_monitor"
|
||||
@@ -89,7 +89,7 @@ class DiskMonitorPlugin(MonitorPlugin):
|
||||
}
|
||||
```
|
||||
|
||||
Place plugins in `hbd/plugins/` and they'll be automatically discovered and loaded by the client.
|
||||
Place plugins in `hbd/client/plugins/` and they'll be automatically discovered and loaded by the client.
|
||||
|
||||
---
|
||||
|
||||
@@ -368,7 +368,7 @@ See [docs/HTTP_API.md](docs/HTTP_API.md) for complete API documentation includin
|
||||
|
||||
Prerequisites:
|
||||
|
||||
- Python 3.10+ (project uses language features from recent Python)
|
||||
- Python 3.11+ (project uses language features from recent Python)
|
||||
- `nsupdate` (for DNS updates) if using dynamic DNS
|
||||
|
||||
Install dependencies (recommended into a venv):
|
||||
@@ -389,7 +389,7 @@ hbd -c .hb.yaml -f -v
|
||||
You can also run it directly via the package entrypoint after installation:
|
||||
|
||||
```bash
|
||||
python -m hbd.cli -c /path/to/config.yaml
|
||||
python -m hbd.server.cli -c /path/to/config.yaml
|
||||
```
|
||||
|
||||
### Running the Client
|
||||
@@ -397,14 +397,23 @@ python -m hbd.cli -c /path/to/config.yaml
|
||||
The heartbeat client (`hbc`) sends periodic heartbeats and plugin data to the server:
|
||||
|
||||
```bash
|
||||
# Basic usage pointing to server
|
||||
python -m hbd.hbc --server your-server.example.com
|
||||
# Basic usage pointing to server (host is a positional argument)
|
||||
hbc your-server.example.com
|
||||
|
||||
# With custom configuration
|
||||
python -m hbd.hbc --server 192.168.1.100 --port 50003 --interval 30
|
||||
# Run as daemon with a config file
|
||||
hbc -d -c /etc/hbc.yaml your-server.example.com
|
||||
|
||||
# Run with specific plugins enabled/disabled
|
||||
python -m hbd.hbc --server hbd.local --disable-plugin os_info
|
||||
# Send a one-off boot message
|
||||
hbc --boot your-server.example.com
|
||||
|
||||
# Verbose output
|
||||
hbc -v your-server.example.com
|
||||
```
|
||||
|
||||
You can also run it via the module entrypoint:
|
||||
|
||||
```bash
|
||||
python -m hbd.client.main your-server.example.com
|
||||
```
|
||||
|
||||
Client configuration can also be specified in YAML:
|
||||
@@ -438,23 +447,23 @@ This repository includes a ready-to-use `.vscode/launch.json` with configuration
|
||||
|
||||
- Ensure the **Python** extension is installed and select the project `.venv` as the interpreter (bottom-left of VS Code).
|
||||
- Use **F5** and pick one of these configurations from the Run view:
|
||||
- **Python: Run hbd (module)** — runs `hbd.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
|
||||
- **Python: Run hbd (module)** — runs `hbd.server.cli` as a module and sets `PYTHONPATH` to the workspace root (recommended).
|
||||
- **Python: Run hbd with debugpy (listen)** — launches `debugpy` and `hbd` together; useful when you want the process to listen for a debugger.
|
||||
- **Python: Attach (localhost:5678)** — attach the debugger to a running process started with `debugpy`.
|
||||
|
||||
To start `hbd` manually and wait for the debugger to attach, run:
|
||||
|
||||
```bash
|
||||
PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.cli -c .hb.yaml -f -v
|
||||
PYTHONPATH=. python -m debugpy --listen 5678 --wait-for-client -m hbd.server.cli -c .hb.yaml -f -v
|
||||
```
|
||||
|
||||
Set breakpoints in modules such as `hbd/udp.py`, `hbd/dns.py`, or `hbd/server.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
|
||||
Set breakpoints in modules such as `hbd/server/udp.py`, `hbd/server/dns.py`, or `hbd/server/main.py`, and use the **Attach** configuration to connect. Use `justMyCode: false` if you need to step into third-party code.
|
||||
|
||||
---
|
||||
|
||||
## 🛠 Configuration
|
||||
|
||||
`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/config.py`):
|
||||
`hbd` reads YAML configuration (optional). If `PyYAML` is not installed, built-in defaults are used. Example configuration keys (see `hbd/server/config.py`):
|
||||
|
||||
- `hb_port`: UDP port to listen for heartbeats (default: 50003)
|
||||
- `hbd_port`: internal control port (default: 50004)
|
||||
@@ -487,29 +496,39 @@ nsupdate_bin: /usr/bin/nsupdate
|
||||
pushsrv: pushover
|
||||
```
|
||||
|
||||
> Tip: `config.DEFAULTS` in `hbd/config.py` contains the canonical defaults and accepted configuration keys.
|
||||
> Tip: `SERVER_DEFAULTS` in `hbd/server/config.py` contains the canonical defaults and accepted configuration keys.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Architecture & Modules
|
||||
|
||||
- `hbd.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
|
||||
- `hbd.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
|
||||
- `hbd.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
|
||||
The DNS worker now runs as an `asyncio` task and the package exposes a
|
||||
small thread-safe bridge so legacy synchronous code can `put()` updates
|
||||
into the queue; there is no longer a permanently-blocking background
|
||||
`threading.Thread`.
|
||||
- `hbd.notify` — email and push notification helpers
|
||||
- `hbd.ws` — WebSocket server and thread-safe broadcast helpers
|
||||
- `hbd.http` — HTTP handler factory for the status UI/API
|
||||
- `hbd.journal` — message journal with size-based log rotation and backup management
|
||||
- `hbd.plugin` — plugin framework with base classes, registry, and dynamic loader
|
||||
- `hbd.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
|
||||
- `hbd.hbc` — heartbeat client that sends heartbeats and plugin data to server
|
||||
- `hbd.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
|
||||
- `hbd.cli` — CLI entrypoint and argument parsing
|
||||
- `hbd.server` — async orchestration to run UDP/HTTP/WSS components
|
||||
The package is organized into three subpackages:
|
||||
|
||||
**`hbd.common`** — shared code used by both client and server:
|
||||
- `hbd.common.proto` — serialization/deserialization of heartbeat messages (supports compressed payloads and plugin data)
|
||||
- `hbd.common.utils` — small utility helpers (`shortname`, `dur`, `initlog`)
|
||||
|
||||
**`hbd.server`** — the heartbeat daemon (`hbd`):
|
||||
- `hbd.server.cli` — CLI entrypoint and argument parsing
|
||||
- `hbd.server.main` — async orchestration to run UDP/HTTP/WSS components
|
||||
- `hbd.server.udp` — UDP parsing and `handle_datagram` implementation (main state machine)
|
||||
- `hbd.server.dns` — `create_nsupdate_payload`, `nsupdate`, and an asyncio DNS worker (`start_dns_worker`).
|
||||
The DNS worker runs as an `asyncio` task and the package exposes a small thread-safe bridge
|
||||
so legacy synchronous code can `put()` updates into the queue.
|
||||
- `hbd.server.notify` — email and push notification helpers
|
||||
- `hbd.server.ws` — WebSocket server and thread-safe broadcast helpers
|
||||
- `hbd.server.http` — HTTP handler factory for the status UI/API
|
||||
- `hbd.server.journal` — message journal with size-based log rotation and backup management
|
||||
- `hbd.server.threshold` — threshold alerting engine
|
||||
- `hbd.server.monitor` — host state monitoring
|
||||
- `hbd.server.hbdclass` — `Host` class and shared server state
|
||||
- `hbd.server.config` — configuration loader and defaults
|
||||
|
||||
**`hbd.client`** — the heartbeat client (`hbc`):
|
||||
- `hbd.client.main` — client entrypoint; sends heartbeats and plugin data to the server
|
||||
- `hbd.client.plugin` — plugin framework with base classes, registry, and dynamic loader
|
||||
- `hbd.client.plugins/` — built-in plugins (os_info, cpu_monitor, memory_monitor, disk_monitor, network_monitor, filesystem_info, nagios_runner)
|
||||
- `hbd.client.config` — client configuration loader
|
||||
|
||||
This modular layout makes the code easier to test and maintain.
|
||||
|
||||
@@ -517,12 +536,12 @@ This modular layout makes the code easier to test and maintain.
|
||||
|
||||
- The main runtime is asyncio-based. Services (UDP listener, HTTP server, WebSocket server, monitor, and DNS worker) run as asyncio tasks.
|
||||
- On SIGINT/SIGTERM the server triggers a graceful shutdown: it cancels active tasks, signals the DNS worker via a sentinel, and cleans up resources before exit.
|
||||
- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.hbdclass.Host.dnsQ`.
|
||||
- The DNS update worker is implemented as an `asyncio` task; synchronous producers can still enqueue DNS updates via a small thread-safe bridge available at `hbd.server.hbdclass.Host.dnsQ`.
|
||||
|
||||
**Templates & Static Files**
|
||||
|
||||
- Template files are located under `hbd/templates` by default. The HTTP server resolves templates relative to the `hbd` package but the path can be overridden with the `templates_dir` config key.
|
||||
- Static assets (CSS/JS/images) are served from `hbd/static` via the `/static/<path>` HTTP route. Place your static files in that directory or configure the HTTP server as needed.
|
||||
- Template files are located under `hbd/server/templates`. The HTTP server resolves templates relative to the `hbd.server` package but the path can be overridden with the `templates_dir` config key.
|
||||
- Static assets (CSS/JS/images) are served from `hbd/server/static` via the `/static/<path>` HTTP route.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user