vikingowl/tyto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive README update for multi-device features

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
vikingowl
2025-12-28 09:01:54 +01:00
parent 62b2dad19d
commit 98a4e76c05
1 changed files with 334 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
README.md
View File

@@ -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)
</div>
@@ -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 <password>
# 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
<details>
@@ -351,10 +664,20 @@ docker compose build frontend
<details>
<summary><b>GPU not detected</b></summary>
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`
</details>