Panoptikon – Watch the world from NixOS

A NixOS module for monitoring website content and command output changes.

Overview

Panoptikon is a generic command output and website watcher that periodically runs scripts and reports changes. It's designed to be flexible and can monitor anything from API endpoints to system metrics.

Features

Flexible Watchers: Monitor any command output or website content
Custom Frequencies: Run scripts at any interval using systemd.timer syntax
Multiple Reporters: Report changes to various destinations (IRC, Telegram, Prometheus, etc.)
Secret Support: Securely pass credentials to scripts without exposing them in the Nix store
Stateful Tracking: Automatically tracks previous output and reports only changes
Modular Design: Easy to extend with custom watchers and reporters

Installation

Add Panoptikon to your NixOS configuration:

{ config, pkgs, ... }:

{
  # Enable Panoptikon service
  services.panoptikon.enable = true;

  # Configure your watchers
  services.panoptikon.watchers = {
    # Your watcher configurations go here
  };
}

Configuration

Basic Watcher Configuration

{
  services.panoptikon.enable = true;
  
  services.panoptikon.watchers = {
    # Monitor GitHub metadata
    github-meta = {
      script = pkgs.writers.writeDash "github-meta" ''
        ${pkgs.curl}/bin/curl -sSL https://api.github.com/meta | ${pkgs.jq}/bin/jq
      '';
      frequency = "*:0/5";  # Every 5 minutes
      reporters = [
        # Report changes to Telegram
        (pkgs.writers.writeDash "telegram-reporter" ''
          ${pkgs.curl}/bin/curl -X POST https://api.telegram.org/bot''${TOKEN}/sendMessage \
            -d chat_id=123456 \
            -d text="$(cat)"
        '')
        # Also show desktop notifications
        (pkgs.writers.writeDash "notify" ''
          ${pkgs.libnotify}/bin/notify-send "$PANOPTIKON_WATCHER has changed."
        '')
      ];
    };

    # Monitor a website for specific content
    nixos-updates = {
      script = pkgs.panoptikon.urlSelector "#news h2" "https://nixos.org/blog/";
      frequency = "daily";
      reporters = [
        # Report to IRC
        (pkgs.panoptikon.kpaste-irc {
          target = "#nixos";
          server = "irc.libera.chat";
          messagePrefix = "New NixOS blog post: ";
        })
      ];
    };

    # Monitor a local command
    disk-space = {
      script = pkgs.writers.writeDash "disk-space" ''
        df -h / | tail -1 | awk '{print $5 " used
        }'';
      frequency = "*:0/30";  # Every 30 minutes
      reporters = [
        # Log to systemd journal
        (pkgs.writers.writeDash "journal-log" ''
          journalctl -t panoptikon-disk-space --since "1 hour ago" | tail -5
        '')
      ];
    };
  };
}

Service Management

systemd Integration

Each watcher gets its own systemd service and timer:

# List all Panoptikon services
systemctl list-units "panoptikon-*"

# Check a specific watcher
systemctl status panoptikon-github-meta

# View logs
journalctl -u panoptikon-github-meta -f

# Trigger a manual run
systemctl start panoptikon-github-meta

Timer Configuration

Timers use systemd timer syntax. Common examples:

*:0/5 - Every 5 minutes
daily - Once per day
*:0/15 - Every 15 minutes
weekly - Once per week

See systemd.time(7) for full syntax.

Security Considerations

Watchers run as the panoptikon system user
Scripts are executed in /var/lib/panoptikon
Use LoadCredential= to securely pass secrets
Scripts should be written defensively (use set -euo pipefail)

Troubleshooting

Examples

See the examples directory for complete configurations.

Run nix run .#panoptikon-vm to start a VM with Panoptikon and example watchers pre-configured.

3.9 KiB Raw Blame History Unescape Escape