vikingowl
52c10b3d55
Documentation structure: - docs/README.md - Documentation index - docs/getting-started.md - Installation and first run - docs/usage.md - Dashboard features and usage - docs/configuration.md - Full configuration reference - docs/multi-device.md - Agent setup and PKI management - docs/security.md - Authentication, RBAC, mTLS - docs/api.md - Complete REST API reference - docs/deployment.md - Production deployment guide - docs/troubleshooting.md - Common issues and solutions - docs/development.md - Contributing and building Total: ~80KB of documentation covering all features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
483 lines
9.6 KiB
Markdown
483 lines
9.6 KiB
Markdown
# Configuration Reference
|
|
|
|
Complete reference for all Tyto configuration options.
|
|
|
|
## Configuration Methods
|
|
|
|
Tyto can be configured via:
|
|
|
|
1. **Environment variables** (highest priority)
|
|
2. **Configuration file** (`config.yaml`)
|
|
3. **Default values** (lowest priority)
|
|
|
|
## Operational Modes
|
|
|
|
```yaml
|
|
mode: standalone # standalone | server | agent
|
|
```
|
|
|
|
| Mode | Description | Database | Use Case |
|
|
|------|-------------|----------|----------|
|
|
| `standalone` | Single-host monitoring | No | Personal servers, dev machines |
|
|
| `server` | Central server | Yes | Multi-device monitoring |
|
|
| `agent` | Reports to server | No | Monitored hosts |
|
|
|
|
## Environment Variables
|
|
|
|
### Core Settings
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `TYTO_MODE` | `standalone` | Operational mode |
|
|
| `TYTO_CONFIG` | `/etc/tyto/config.yaml` | Config file path |
|
|
| `TYTO_REFRESH_RATE` | `5` | Collection interval (seconds) |
|
|
| `TYTO_LOG_LEVEL` | `info` | Log level: debug, info, warn, error |
|
|
| `TYTO_LOG_FORMAT` | `text` | Log format: text, json |
|
|
|
|
### HTTP Server
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | `8080` | HTTP server port |
|
|
| `TYTO_HTTP_HOST` | `0.0.0.0` | HTTP bind address |
|
|
| `TYTO_HTTP_READ_TIMEOUT` | `30s` | Read timeout |
|
|
| `TYTO_HTTP_WRITE_TIMEOUT` | `30s` | Write timeout |
|
|
|
|
### Database (Server Mode)
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `TYTO_DB_TYPE` | `sqlite` | Database type: sqlite, postgres |
|
|
| `TYTO_DB_PATH` | `/var/lib/tyto/tyto.db` | SQLite file path |
|
|
| `TYTO_DB_URL` | | PostgreSQL connection string |
|
|
|
|
### Collector Paths
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `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 |
|
|
|
|
## Configuration File
|
|
|
|
Default location: `/etc/tyto/config.yaml`
|
|
|
|
### Full Example
|
|
|
|
```yaml
|
|
# Operational mode
|
|
mode: standalone
|
|
|
|
# HTTP server configuration
|
|
http:
|
|
host: "0.0.0.0"
|
|
port: 8080
|
|
read_timeout: 30s
|
|
write_timeout: 30s
|
|
|
|
# Metric collection
|
|
refresh_rate: 5
|
|
|
|
# Logging
|
|
logging:
|
|
level: info # debug, info, warn, error
|
|
format: text # text, json
|
|
|
|
# Database (server mode only)
|
|
database:
|
|
type: sqlite # sqlite, postgres
|
|
path: /var/lib/tyto/tyto.db
|
|
# For PostgreSQL:
|
|
# type: postgres
|
|
# url: postgres://user:pass@localhost:5432/tyto?sslmode=require
|
|
|
|
# Data retention
|
|
retention:
|
|
raw: 24h # Full resolution metrics
|
|
one_minute: 168h # 7 days
|
|
five_minute: 720h # 30 days
|
|
hourly: 8760h # 1 year
|
|
logs: 168h # 7 days
|
|
|
|
# gRPC server (server mode)
|
|
server:
|
|
grpc_port: 9849
|
|
tls:
|
|
enabled: false
|
|
ca_cert: /etc/tyto/pki/ca.crt
|
|
server_cert: /etc/tyto/certs/server.crt
|
|
server_key: /etc/tyto/certs/server.key
|
|
registration:
|
|
auto_enabled: true
|
|
require_approval: true
|
|
|
|
# Agent settings (agent mode)
|
|
agent:
|
|
id: "" # Auto-generated if empty
|
|
server_url: tyto-server: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
|
|
|
|
# Log collection
|
|
logs:
|
|
enabled: false
|
|
buffer_size: 1000
|
|
flush_interval: 5s
|
|
|
|
journal:
|
|
enabled: true
|
|
units: [] # Empty = all units
|
|
priority: 6 # 0=emerg to 7=debug
|
|
|
|
files: []
|
|
# - path: /var/log/nginx/access.log
|
|
# format: nginx
|
|
# - path: /var/log/app/*.log
|
|
# format: json
|
|
|
|
docker:
|
|
enabled: false
|
|
containers: [] # Empty = all containers
|
|
|
|
# Authentication (server mode)
|
|
auth:
|
|
enabled: true
|
|
session_duration: 24h
|
|
allow_registration: false
|
|
|
|
ldap:
|
|
enabled: false
|
|
url: ldap://ad.example.com:389
|
|
base_dn: dc=example,dc=com
|
|
bind_dn: cn=readonly,dc=example,dc=com
|
|
bind_password: ""
|
|
user_filter: (sAMAccountName=%s)
|
|
group_filter: (member=%s)
|
|
username_attr: sAMAccountName
|
|
email_attr: mail
|
|
tls: false
|
|
insecure_skip_verify: false
|
|
group_mappings: {}
|
|
|
|
# Alerting
|
|
alerts:
|
|
enabled: true
|
|
thresholds:
|
|
cpu:
|
|
warning: 80
|
|
critical: 95
|
|
memory:
|
|
warning: 85
|
|
critical: 95
|
|
disk:
|
|
warning: 80
|
|
critical: 90
|
|
|
|
# Collector paths (for containerized deployments)
|
|
paths:
|
|
proc: /proc
|
|
sys: /sys
|
|
mtab: /etc/mtab
|
|
docker_socket: /var/run/docker.sock
|
|
dbus_socket: /run/dbus/system_bus_socket
|
|
```
|
|
|
|
## Database Configuration
|
|
|
|
### SQLite
|
|
|
|
Default for simple deployments:
|
|
|
|
```yaml
|
|
database:
|
|
type: sqlite
|
|
path: /var/lib/tyto/tyto.db
|
|
```
|
|
|
|
**File permissions**: The Tyto user must have read/write access to the database file and its directory.
|
|
|
|
### PostgreSQL
|
|
|
|
For high availability and larger deployments:
|
|
|
|
```yaml
|
|
database:
|
|
type: postgres
|
|
url: postgres://tyto:password@localhost:5432/tyto?sslmode=require
|
|
```
|
|
|
|
**Connection string options:**
|
|
- `sslmode=disable` - No SSL
|
|
- `sslmode=require` - SSL required
|
|
- `sslmode=verify-ca` - Verify CA certificate
|
|
- `sslmode=verify-full` - Verify CA and hostname
|
|
|
|
**Create database:**
|
|
```sql
|
|
CREATE DATABASE tyto;
|
|
CREATE USER tyto WITH PASSWORD 'your-password';
|
|
GRANT ALL PRIVILEGES ON DATABASE tyto TO tyto;
|
|
```
|
|
|
|
## Data Retention
|
|
|
|
Configure how long metrics are stored:
|
|
|
|
```yaml
|
|
retention:
|
|
raw: 24h # Full resolution (as collected)
|
|
one_minute: 168h # Aggregated to 1-minute intervals
|
|
five_minute: 720h # Aggregated to 5-minute intervals
|
|
hourly: 8760h # Aggregated to hourly intervals
|
|
logs: 168h # Log entries
|
|
```
|
|
|
|
**Aggregation**: Raw metrics are automatically aggregated to lower resolutions. Aggregated data includes min, max, and average values.
|
|
|
|
## Volume Mounts
|
|
|
|
### Required Mounts
|
|
|
|
For host metric collection:
|
|
|
|
```yaml
|
|
volumes:
|
|
- /proc:/host/proc:ro
|
|
- /sys:/host/sys:ro
|
|
- /etc/mtab:/host/etc/mtab:ro
|
|
```
|
|
|
|
Set paths in config:
|
|
```yaml
|
|
paths:
|
|
proc: /host/proc
|
|
sys: /host/sys
|
|
mtab: /host/etc/mtab
|
|
```
|
|
|
|
### Optional Mounts
|
|
|
|
**Docker monitoring:**
|
|
```yaml
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
```
|
|
|
|
**Systemd monitoring:**
|
|
```yaml
|
|
volumes:
|
|
- /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro
|
|
```
|
|
|
|
## Agent Log Collection
|
|
|
|
### Systemd Journal
|
|
|
|
```yaml
|
|
agent:
|
|
logs:
|
|
journal:
|
|
enabled: true
|
|
units:
|
|
- nginx.service
|
|
- docker.service
|
|
- postgresql.service
|
|
priority: 4 # warning and above
|
|
```
|
|
|
|
**Priority levels:**
|
|
| Level | Name |
|
|
|-------|------|
|
|
| 0 | Emergency |
|
|
| 1 | Alert |
|
|
| 2 | Critical |
|
|
| 3 | Error |
|
|
| 4 | Warning |
|
|
| 5 | Notice |
|
|
| 6 | Info |
|
|
| 7 | Debug |
|
|
|
|
### File Tailing
|
|
|
|
```yaml
|
|
agent:
|
|
logs:
|
|
files:
|
|
- path: /var/log/nginx/access.log
|
|
format: nginx
|
|
- path: /var/log/nginx/error.log
|
|
format: nginx_error
|
|
- path: /var/log/app/*.log
|
|
format: json
|
|
- path: /var/log/syslog
|
|
format: plain
|
|
```
|
|
|
|
**Supported formats:**
|
|
| Format | Description |
|
|
|--------|-------------|
|
|
| `plain` | Plain text, one line per entry |
|
|
| `json` | JSON objects, one per line |
|
|
| `nginx` | Nginx access log format |
|
|
| `nginx_error` | Nginx error log format |
|
|
|
|
### Docker Logs
|
|
|
|
```yaml
|
|
agent:
|
|
logs:
|
|
docker:
|
|
enabled: true
|
|
containers:
|
|
- nginx
|
|
- app
|
|
- db
|
|
# Empty list = all containers
|
|
```
|
|
|
|
## LDAP Configuration
|
|
|
|
```yaml
|
|
auth:
|
|
ldap:
|
|
enabled: true
|
|
url: ldap://ad.example.com:389
|
|
base_dn: dc=example,dc=com
|
|
bind_dn: cn=svc-tyto,ou=Service Accounts,dc=example,dc=com
|
|
bind_password: ${LDAP_BIND_PASSWORD} # Use env var
|
|
user_filter: (sAMAccountName=%s)
|
|
group_filter: (member=%s)
|
|
username_attr: sAMAccountName
|
|
email_attr: mail
|
|
tls: true
|
|
insecure_skip_verify: false
|
|
group_mappings:
|
|
"CN=Tyto Admins,OU=Groups,DC=example,DC=com": admin
|
|
"CN=Tyto Operators,OU=Groups,DC=example,DC=com": operator
|
|
"CN=Tyto Viewers,OU=Groups,DC=example,DC=com": viewer
|
|
```
|
|
|
|
## TLS/mTLS Configuration
|
|
|
|
### Server TLS
|
|
|
|
```yaml
|
|
server:
|
|
tls:
|
|
enabled: true
|
|
ca_cert: /etc/tyto/pki/ca.crt
|
|
server_cert: /etc/tyto/certs/server.crt
|
|
server_key: /etc/tyto/certs/server.key
|
|
```
|
|
|
|
### Agent mTLS
|
|
|
|
```yaml
|
|
agent:
|
|
tls:
|
|
ca_cert: /etc/tyto/certs/ca.crt
|
|
agent_cert: /etc/tyto/certs/agent.crt
|
|
agent_key: /etc/tyto/certs/agent.key
|
|
```
|
|
|
|
## Alert Thresholds
|
|
|
|
```yaml
|
|
alerts:
|
|
enabled: true
|
|
thresholds:
|
|
cpu:
|
|
warning: 80
|
|
critical: 95
|
|
memory:
|
|
warning: 85
|
|
critical: 95
|
|
disk:
|
|
warning: 80
|
|
critical: 90
|
|
temperature:
|
|
warning: 70
|
|
critical: 85
|
|
```
|
|
|
|
## Example Configurations
|
|
|
|
### Minimal Standalone
|
|
|
|
```yaml
|
|
mode: standalone
|
|
http:
|
|
port: 8080
|
|
refresh_rate: 5
|
|
```
|
|
|
|
### Production Server
|
|
|
|
```yaml
|
|
mode: server
|
|
|
|
http:
|
|
port: 8080
|
|
|
|
database:
|
|
type: postgres
|
|
url: postgres://tyto:${DB_PASSWORD}@db.example.com:5432/tyto?sslmode=require
|
|
|
|
server:
|
|
grpc_port: 9849
|
|
tls:
|
|
enabled: true
|
|
ca_cert: /etc/tyto/pki/ca.crt
|
|
server_cert: /etc/tyto/certs/server.crt
|
|
server_key: /etc/tyto/certs/server.key
|
|
|
|
auth:
|
|
enabled: true
|
|
ldap:
|
|
enabled: true
|
|
url: ldaps://ad.example.com:636
|
|
# ... LDAP config
|
|
|
|
logging:
|
|
level: warn
|
|
format: json
|
|
|
|
retention:
|
|
raw: 24h
|
|
one_minute: 168h
|
|
five_minute: 720h
|
|
hourly: 8760h
|
|
```
|
|
|
|
### Agent with Log Collection
|
|
|
|
```yaml
|
|
mode: agent
|
|
|
|
agent:
|
|
id: web-server-01
|
|
server_url: tyto.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
|
|
|
|
logs:
|
|
enabled: true
|
|
journal:
|
|
enabled: true
|
|
units: [nginx.service, php-fpm.service]
|
|
priority: 4
|
|
files:
|
|
- path: /var/log/nginx/access.log
|
|
format: nginx
|
|
docker:
|
|
enabled: true
|
|
```
|