tyto/docs/configuration.md

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

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

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

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:

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:

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:

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:

volumes:
  - /proc:/host/proc:ro
  - /sys:/host/sys:ro
  - /etc/mtab:/host/etc/mtab:ro

Set paths in config:

paths:
  proc: /host/proc
  sys: /host/sys
  mtab: /host/etc/mtab

Optional Mounts

Docker monitoring:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Systemd monitoring:

volumes:
  - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro

Agent Log Collection

Systemd Journal

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

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

agent:
  logs:
    docker:
      enabled: true
      containers:
        - nginx
        - app
        - db
      # Empty list = all containers

LDAP Configuration

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

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

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

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

mode: standalone
http:
  port: 8080
refresh_rate: 5

Production Server

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

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