# 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
```