142 lines
3.9 KiB
Markdown
142 lines
3.9 KiB
Markdown
# 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:
|
||
|
||
```nix
|
||
{ config, pkgs, ... }:
|
||
|
||
{
|
||
# Enable Panoptikon service
|
||
services.panoptikon.enable = true;
|
||
|
||
# Configure your watchers
|
||
services.panoptikon.watchers = {
|
||
# Your watcher configurations go here
|
||
};
|
||
}
|
||
```
|
||
|
||
## Configuration
|
||
|
||
### Basic Watcher Configuration
|
||
|
||
```nix
|
||
{
|
||
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:
|
||
|
||
```bash
|
||
# 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)](https://www.freedesktop.org/software/systemd/man/systemd.time.html) 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](./examples/) for complete configurations.
|
||
|
||
Run `nix run .#panoptikon-vm` to start a VM with Panoptikon and example watchers pre-configured.
|