From 98a4e76c05784cc136f0d481f2d7b36ab8967947 Mon Sep 17 00:00:00 2001 From: vikingowl Date: Sun, 28 Dec 2025 09:01:54 +0100 Subject: [PATCH] docs: comprehensive README update for multi-device features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update GPU section for multi-vendor support (NVIDIA, AMD, Intel) - Add Authentication section with local and LDAP documentation - Add RBAC documentation with permission reference - Add Log Collection section with agent configuration - Expand API Reference with auth, users, roles, agents, logs endpoints - Add Operational Modes section (standalone, server, agent) - Add Database Configuration for SQLite and PostgreSQL - Add Data Retention configuration reference - Add Deployment section with PKI setup and agent configuration - Update project structure to reflect new directories - Update troubleshooting for multi-vendor GPU support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 345 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 334 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f766d34..ce9f32b 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ ![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker) ![License](https://img.shields.io/badge/License-MIT-green?style=flat-square) -**A real-time Linux system monitoring dashboard with a modern web interface** +**A real-time Linux system monitoring dashboard with multi-device support** *Named after Tyto alba, the barn owl — nature's silent, watchful guardian* -[Features](#features) • [Quick Start](#quick-start) • [Multi-Host Setup](#multi-host-monitoring) • [API](#api-reference) • [Development](#development) +[Features](#features) • [Quick Start](#quick-start) • [Multi-Device Setup](#multi-device-monitoring) • [Authentication](#authentication) • [API](#api-reference) • [Development](#development) @@ -44,12 +44,16 @@ Tyto is a lightweight, containerized monitoring solution that provides real-time | **Network** | Interface stats, bandwidth rates, TCP connections | | **Processes** | Top by CPU/Memory, detailed view, signal control | | **Temperature** | Hardware sensors via hwmon | -| **GPU** | AMD GPU monitoring (utilization, VRAM, power, clocks) | +| **GPU** | Multi-vendor support: NVIDIA, AMD, Intel (utilization, VRAM, power, clocks) | | **Docker** | Container stats (CPU, memory, status) | | **Systemd** | Service status monitoring | | **Alerts** | Configurable thresholds with desktop notifications | | **History** | Sparkline charts for CPU, memory, network, disk I/O | | **Export** | CSV and JSON export of current metrics | +| **Logs** | Centralized log collection from journal, files, Docker | +| **Authentication** | Local accounts and LDAP/AD integration | +| **RBAC** | Role-based access control with customizable permissions | +| **Multi-Device** | Central server with lightweight agents via mTLS | --- @@ -80,18 +84,66 @@ open http://localhost:9847 ## Configuration -### Environment Variables +### Operational Modes -The backend container supports the following environment variables: +Tyto supports three operational modes: + +| Mode | Description | +|------|-------------| +| `standalone` | Single-host monitoring, no database required (default) | +| `server` | Central server for multi-device monitoring with database | +| `agent` | Lightweight agent that reports to a central server | + +Set the mode via environment variable or config file: +```bash +TYTO_MODE=server tyto +``` + +### Environment Variables | Variable | Default | Description | |----------|---------|-------------| -| `PORT` | `8080` | Backend server port | +| `TYTO_MODE` | `standalone` | Operational mode | +| `TYTO_REFRESH_RATE` | `5` | Metric collection interval (seconds) | +| `TYTO_LOG_LEVEL` | `info` | Log level (debug, info, warn, error) | +| `TYTO_DB_TYPE` | `sqlite` | Database type (sqlite, postgres) | +| `TYTO_DB_PATH` | `/data/tyto.db` | SQLite database path | +| `TYTO_DB_URL` | | PostgreSQL connection string | +| `PORT` | `8080` | HTTP server port | | `PROC_PATH` | `/proc` | Path to proc filesystem | | `SYS_PATH` | `/sys` | Path to sys filesystem | | `MTAB_PATH` | `/etc/mtab` | Path to mount table | | `DOCKER_SOCKET` | `/var/run/docker.sock` | Docker socket path | -| `DEFAULT_REFRESH_INTERVAL` | `5s` | Default metric collection interval | + +### Database Configuration + +**SQLite** (default, recommended for single server): +```yaml +database: + type: sqlite + path: /var/lib/tyto/tyto.db +``` + +**PostgreSQL** (for high availability): +```yaml +database: + type: postgres + url: postgres://user:pass@localhost:5432/tyto?sslmode=require +``` + +### Data Retention + +Configure metric retention with tiered aggregation: + +```yaml +database: + retention: + raw: 24h # Full resolution + one_minute: 168h # 7 days + five_minute: 720h # 30 days + hourly: 8760h # 1 year + logs: 168h # 7 days +``` ### Required Volume Mounts @@ -179,10 +231,69 @@ Host configurations are stored in browser localStorage under the key `tyto-hosts --- +## Authentication + +Tyto supports multiple authentication methods for securing access to the dashboard. + +### Local Authentication + +Local user accounts with username/password stored in the database (bcrypt hashed). + +```bash +# Create initial admin user during setup +tyto setup --admin-user admin --admin-pass + +# Or via API after setup +curl -X POST http://localhost:9847/api/v1/auth/register \ + -H "Content-Type: application/json" \ + -d '{"username": "admin", "password": "secret", "email": "admin@example.com"}' +``` + +### LDAP/Active Directory + +Configure LDAP authentication in `config.yaml`: + +```yaml +auth: + ldap: + enabled: true + url: ldap://ad.example.com:389 + base_dn: dc=example,dc=com + bind_dn: cn=readonly,dc=example,dc=com + bind_password: ${LDAP_BIND_PASSWORD} + user_filter: (sAMAccountName=%s) + group_mappings: + "CN=Tyto Admins,OU=Groups,DC=example,DC=com": admin + "CN=Tyto Operators,OU=Groups,DC=example,DC=com": operator +``` + +### Role-Based Access Control (RBAC) + +Tyto includes a flexible permission system with three built-in roles: + +| Role | Permissions | +|------|-------------| +| **Administrator** | Full system access (`*`) | +| **Operator** | Manage agents, alerts, view/export metrics | +| **Viewer** | Read-only dashboard access | + +Custom roles can be created via the Admin panel with granular permissions: +- `dashboard:view` - View dashboard +- `agents:view`, `agents:manage` - Agent management +- `alerts:view`, `alerts:acknowledge`, `alerts:configure` - Alert handling +- `users:view`, `users:manage` - User management +- `roles:view`, `roles:manage` - Role management +- `metrics:export`, `metrics:query` - Metrics access +- `pki:manage` - Certificate management + +--- + ## API Reference ### Endpoints +#### Metrics & Monitoring + | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/v1/stream` | SSE stream of real-time metrics | @@ -196,6 +307,51 @@ Host configurations are stored in browser localStorage under the key `tyto-hosts | `GET` | `/api/v1/export/metrics?format=csv\|json` | Export current metrics | | `GET` | `/health` | Health check endpoint | +#### Authentication + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/api/v1/auth/login` | Login with username/password | +| `POST` | `/api/v1/auth/logout` | Logout (invalidate session) | +| `POST` | `/api/v1/auth/register` | Register new user (if enabled) | +| `GET` | `/api/v1/auth/me` | Get current user info | +| `PUT` | `/api/v1/auth/me` | Update current user profile | +| `PUT` | `/api/v1/auth/me/password` | Change password | + +#### User & Role Management + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/api/v1/users` | List all users | +| `POST` | `/api/v1/users` | Create new user | +| `GET` | `/api/v1/users/:id` | Get user details | +| `PUT` | `/api/v1/users/:id` | Update user | +| `DELETE` | `/api/v1/users/:id` | Disable user | +| `GET` | `/api/v1/roles` | List all roles | +| `POST` | `/api/v1/roles` | Create custom role | +| `PUT` | `/api/v1/roles/:id` | Update role | +| `DELETE` | `/api/v1/roles/:id` | Delete custom role | + +#### Agent Management + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/api/v1/agents` | List all agents | +| `GET` | `/api/v1/agents/:id` | Get agent details | +| `POST` | `/api/v1/agents` | Add agent manually | +| `DELETE` | `/api/v1/agents/:id` | Remove agent | +| `POST` | `/api/v1/agents/:id/revoke` | Revoke agent certificate | +| `GET` | `/api/v1/agents/pending` | List pending registrations | +| `POST` | `/api/v1/agents/pending/:id/approve` | Approve agent | +| `POST` | `/api/v1/agents/pending/:id/reject` | Reject agent | + +#### Logs + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/api/v1/logs` | Query logs with filters | +| `GET` | `/api/v1/logs/stream` | SSE stream of live logs | + ### SSE Stream Format The `/api/v1/stream` endpoint sends JSON messages with this structure: @@ -271,27 +427,45 @@ npm test ``` tyto/ ├── backend/ -│ ├── cmd/server/ # Main entry point +│ ├── cmd/ +│ │ ├── server/ # HTTP/SSE server entry point +│ │ ├── agent/ # Lightweight agent entry point +│ │ └── tyto/ # CLI tool (pki, setup) │ ├── internal/ │ │ ├── api/ # HTTP handlers and routes │ │ ├── alerts/ # Alert management +│ │ ├── auth/ # Authentication (local, LDAP) │ │ ├── collectors/ # Metric collectors +│ │ │ ├── gpu/ # Multi-vendor GPU support +│ │ │ └── logs/ # Log collectors │ │ ├── config/ # Configuration +│ │ ├── database/ # SQLite/PostgreSQL abstraction │ │ ├── history/ # Historical data storage │ │ ├── models/ # Data structures +│ │ ├── pki/ # Certificate management +│ │ ├── server/ # gRPC hub for agents │ │ └── sse/ # Server-Sent Events broker +│ ├── proto/ # gRPC protocol definitions │ └── Dockerfile ├── frontend/ │ ├── src/ │ │ ├── lib/ │ │ │ ├── api/ # API clients │ │ │ ├── components/ # Svelte components +│ │ │ │ ├── auth/ # Login, UserMenu +│ │ │ │ └── admin/ # User/Role management │ │ │ ├── stores/ # Svelte stores │ │ │ ├── types/ # TypeScript types │ │ │ └── utils/ # Utility functions │ │ └── routes/ # SvelteKit routes +│ │ ├── admin/ # Admin pages +│ │ ├── login/ # Login page +│ │ └── logs/ # Log viewer │ └── Dockerfile -└── docker-compose.yaml +├── scripts/ +│ └── install.sh # One-line installer +├── docker-compose.yml # Base configuration +└── docker-compose.prod.yml # Production overrides ``` ### Building Docker Images @@ -307,6 +481,86 @@ docker compose build frontend --- +## Deployment + +### One-Line Installation + +Install Tyto on any Linux system: + +```bash +# Server installation +curl -fsSL https://raw.githubusercontent.com/vikingowl/tyto/main/scripts/install.sh | sudo bash + +# Agent installation +curl -fsSL https://raw.githubusercontent.com/vikingowl/tyto/main/scripts/install.sh | \ + sudo TYTO_MODE=agent bash +``` + +### PKI Setup (mTLS) + +For secure multi-device deployments, set up mTLS certificates: + +```bash +# Initialize Certificate Authority (on server) +tyto pki init-ca --cn "Tyto CA" --out /etc/tyto/pki/ + +# Generate server certificate +tyto pki gen-server --ca-dir /etc/tyto/pki/ --dns tyto.example.com + +# Generate agent certificates +tyto pki gen-agent --ca-dir /etc/tyto/pki/ --agent-id web-server-01 +tyto pki gen-agent --ca-dir /etc/tyto/pki/ --agent-id db-server-01 + +# List certificates +tyto pki list --ca-dir /etc/tyto/pki/ + +# Revoke a compromised certificate +tyto pki revoke --serial ABC123 --ca-dir /etc/tyto/pki/ +``` + +### Agent Configuration + +Deploy the agent on each monitored host: + +```yaml +# /etc/tyto/config.yaml +mode: agent + +agent: + id: web-server-01 + server_url: tyto-server.example.com:9849 + interval: 5s + tls: + ca_cert: /etc/tyto/certs/ca.crt + agent_cert: /etc/tyto/certs/agent.crt + agent_key: /etc/tyto/certs/agent.key +``` + +### Systemd Service + +Tyto installs as a systemd service: + +```bash +# Check status +systemctl status tyto + +# View logs +journalctl -u tyto -f + +# Restart +systemctl restart tyto +``` + +### Production Docker Compose + +Use the production overlay for resource limits: + +```bash +docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d +``` + +--- + ## Keyboard Shortcuts | Key | Action | @@ -337,6 +591,65 @@ docker compose build frontend --- +## Log Collection + +Tyto can collect and aggregate logs from multiple sources across all monitored hosts. + +### Supported Sources + +| Source | Description | +|--------|-------------| +| **Systemd Journal** | System and service logs via journalctl | +| **File** | Tail log files with format parsing | +| **Docker** | Container stdout/stderr logs | + +### Agent Log Configuration + +Configure log collection in the agent's `config.yaml`: + +```yaml +agent: + logs: + enabled: true + buffer_size: 1000 + flush_interval: 5s + + journal: + enabled: true + units: # Empty = all units + - nginx.service + - docker.service + priority: 4 # 0=emerg to 7=debug + + files: + - path: /var/log/nginx/access.log + format: nginx + - path: /var/log/app/*.log + format: json + + docker: + enabled: true + containers: [] # Empty = all containers +``` + +### Log Query Parameters + +``` +GET /api/v1/logs?agent_id=web-01&level=error,warn&limit=100 +``` + +| Parameter | Description | +|-----------|-------------| +| `agent_id` | Filter by agent | +| `source` | Filter by source type (journal, file, docker) | +| `source_name` | Filter by source name (unit, filename, container) | +| `level` | Comma-separated levels (debug, info, warning, error, fatal) | +| `q` | Full-text search in message | +| `from`, `to` | Time range (ISO 8601) | +| `limit`, `offset` | Pagination | + +--- + ## Troubleshooting
@@ -351,10 +664,20 @@ docker compose build frontend
GPU not detected -AMD GPU monitoring requires: +**AMD GPU** requires: - AMD GPU with amdgpu driver - `/sys/class/drm/card*/device/` accessible -- Proper volume mount: `-v /sys:/host/sys:ro` +- Volume mount: `-v /sys:/host/sys:ro` + +**NVIDIA GPU** requires: +- NVIDIA driver installed on host +- `nvidia-smi` available in PATH +- For Docker: `--gpus all` or nvidia-container-toolkit + +**Intel GPU** requires: +- Intel GPU with i915 or xe driver +- `/sys/class/drm/card*/` accessible +- Volume mount: `-v /sys:/host/sys:ro`