diff --git a/DATABASE.md b/DATABASE.md index 4785309..12e3c24 100644 --- a/DATABASE.md +++ b/DATABASE.md @@ -24,7 +24,7 @@ what the app actually creates. | **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. | | **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. | | **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. | -| **Tables** | 21 application tables, plus drizzle's own `__drizzle_migrations`. | +| **Tables** | 22 application tables, plus drizzle's own `__drizzle_migrations`. | **Not in the database:** @@ -58,6 +58,7 @@ erDiagram servers ||--o{ server_ports : "cascade" servers ||--o{ port_forwards : "optional (set null)" integrations ||--o{ servers : "proxmox link (app clears it)" + integrations ||--o{ alert_tickets : "osTicket used (set null)" ``` Eight tables stand alone, with no foreign keys: `settings`, `secrets`, @@ -95,7 +96,7 @@ Who changed what. Written by the app on every change (see | `id` | integer PK | | | `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. | | `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. | -| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`. | +| `category` | text NOT NULL | Free text. In use: `server`, `integration`, `dns`, `settings`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`. | | `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. | | `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. | | `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. | @@ -405,6 +406,25 @@ Consistency findings someone looked at and decided are fine. | `reason`, `created_by` | text | | | `created_at` | text NOT NULL | | +#### `alert_tickets` + +What the "open an osTicket ticket for an alert" feature remembers about each problem it has seen, so one problem opens one ticket however many +checks see it. A row is one *occurrence*: when an alert clears and later returns for good, that is a new row. + +| Column | Type | Notes | +|---|---|---| +| `id` | integer PK | | +| `alert_key` | text NOT NULL, indexed | The alert's id as the Alerts page shows it (e.g. `disk:server:3:/`). Not a foreign key — alerts aren't stored. | +| `status` | text NOT NULL | `pending` (seen, not yet in enough checks in a row), `open` (a ticket was opened), `baseline` (already there when the feature was switched on, left alone). | +| `seen_count` | integer NOT NULL, default 1 | Checks in a row it has been seen while pending. | +| `integration_id` | integer → `integrations.id`, **set null** | The osTicket integration the ticket went to. | +| `ticket_number` | text | osTicket's own number; null unless `open`. | +| `grouped` | bool NOT NULL, default 0 | Part of a summary ticket that covers several alerts (they share a number). | +| `severity`, `message` | text NOT NULL | What the alert said when it was recorded. | +| `first_seen_at`, `last_seen_at` | text NOT NULL | ISO. | +| `ticketed_at` | text | ISO; when the ticket was opened. | +| `cleared_at` | text | ISO; null while the alert is still active. Rows cleared more than 180 days ago are deleted. | + ## What's stored inside the JSON columns | Column | Shape | @@ -446,6 +466,7 @@ that were never changed aren't stored; the app fills in defaults when reading. | `display` | `dateFormat`, `timeFormat`, `pageSize`. | | `providerColors`, `integrationColors` | Badge colours, by provider / integration type. | | `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). | +| `alertTickets` | Opening osTicket tickets for alerts: `enabled`, `integrationId`, `severities`, `categories`, `requesterName`/`requesterEmail`, `topicId`, `priorityId`, `notifyStaff`, `existingProblems`, `confirmChecks`, `summaryAbove`, `reopenAfterMinutes`. Edited under Settings → Alert tickets. The API address and key are on the osTicket integration, not here. | | `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. | Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not @@ -455,6 +476,7 @@ settings, and aren't part of the app's settings object: |---|---| | `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). | | `_internal:logRetentionLastRunAt` | When the log purge last ran. | +| `_internal:alertTicketsBaselineDone`, `_internal:alertTicketsLastRun` | Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result. | | `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. | ## What happens on delete @@ -464,6 +486,7 @@ settings, and aren't part of the app's settings object: | a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. | | a **DNS provider** | Its cached zones and records are deleted. | | an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). | +| an **integration** used for alert tickets | `alert_tickets.integration_id` is cleared; the history stays. | | an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. | | a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. | | a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. | diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index 8d7793f..de87e45 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -116,8 +116,8 @@ the dashboard views themselves load fine. reading osTicket's own MySQL/MariaDB database directly, the same way osTicket's own admin panel does internally. This makes it the only integration in this app that isn't a REST API. - **Actions used:** read-only — a single `SELECT` joining the ticket, status, priority, department, staff, team, - and requester tables for every ticket whose status is in the "open" state. Nothing here can create, update, or - close a ticket. + and requester tables for every ticket whose status is in the "open" state. Nothing in this part can create, + update, or close a ticket — opening tickets is the separate, optional API described below. - **Required access:** a MySQL/MariaDB user with **read-only (`SELECT`) access to the osTicket database only** — never reuse osTicket's own application database user, which has full read/write access. Create one with something like: @@ -148,6 +148,25 @@ the dashboard views themselves load fine. a field looks wrong, tell us what happened and we'll adjust — this one has had less real-world exposure than every other integration listed here. +**Optional: opening tickets for alerts** (Settings → Alert tickets) + +- **Config fields:** Ticket API address (optional), Ticket API key (optional, stored encrypted like the database + password), Allow self-signed certificate (ticket API). Leave them empty and the integration works as before. +- **Auth:** osTicket's own HTTP API: `POST
/api/tickets.json` with the key in an `X-API-Key` header. +- **Make the key in osTicket:** Admin Panel → Manage → API Keys → Add. Tie it to the IP address osTicket sees this + app's requests come from (behind Docker or a reverse proxy that is the host's or proxy's address, not the + container's — check osTicket's log if it refuses) and tick **Can create tickets**. osTicket refuses a key from any + other address, which is the most common reason a test ticket fails. +- **What is sent:** one ticket per problem — name and email you set under Settings → Alert tickets, a subject, the + problem's text and a link back to this app, optionally a help topic and priority id — with `autorespond` off (the + "user" is this app, so an acknowledgement would only bounce) and osTicket's own staff alert on or off as you choose. +- **What it can't do:** close, reopen, or comment on a ticket — osTicket's API has no such endpoint. A ticket opened + here is yours to close in osTicket. +- **Not verified against a real osTicket** — built from osTicket's published API documentation and tested against a + stand-in server that checks what is sent (the key header, the JSON fields, the message encoding, and how each + answer — created, refused key, bad request, redirect — is handled). If osTicket rejects a ticket, "Send a test + ticket" shows the reason it gave. + ### phpIPAM - **Config fields:** phpIPAM URL, API app ID, App token diff --git a/NOTIFICATIONS.md b/NOTIFICATIONS.md index 9b95336..b9d58bd 100644 --- a/NOTIFICATIONS.md +++ b/NOTIFICATIONS.md @@ -101,16 +101,40 @@ in three ways: failing its last few calls (before the threshold that triggers an "integration down" notification). It runs the checks live when opened (a recent result is reused for a minute), and shows what it couldn't read at the top, so a missing section means -"couldn't check" and not "all clear". +"couldn't check" and not "all clear". An alert that has an osTicket ticket (see the next section) shows its ticket number. + +## Tickets in osTicket + +Not a notification, but it acts on the same alerts: with **Settings → Alert tickets** switched on (off by default), a problem on the Alerts page opens a +ticket in osTicket. It runs every 15 minutes, starting about a minute and a half after the app starts. + +| Rule | What it means | +|---|---| +| Which problems | The severities and kinds you choose — **critical and warning, every kind** by default. Info (updates waiting and the like) is off. | +| Must last | A problem must be there in **2 checks in a row** (15–30 minutes) before it opens a ticket, so a blip that fixes itself — one failed call to an integration, a monitor that flickers — never does. Can be set from 1 (at once) to 4. | +| One ticket per problem | However many checks see it, once. After a ticket is open, the problem isn't ticketed again while it lasts — even if someone closes the ticket in osTicket. | +| Comes back | A problem that clears and returns **within 60 minutes** is the same problem (no new ticket). After longer, it is a new one and gets a new ticket. | +| Many at once | **More than 5 new problems in one check** become a single summary ticket listing them all, so one outage doesn't fill the queue. Up to 5 get a ticket each. | +| Maintenance windows | A problem under one never opens a ticket. If it is still there after the window ends, it does. | +| Never about osTicket | Overdue tickets, and osTicket's own calls failing, never open a ticket — it would go to the thing that is down, or add to the pile. | +| Already there at switch-on | **Left alone by default**: the first check after switching on records what is wrong as the starting line, and only problems that start after it get a ticket. Can be set to ticket those too. Switching it off and on again starts a new line. | +| If osTicket can't be reached | Nothing is recorded as opened; the next check tries again. A refused key, a wrong address and similar are shown on the settings page and in the Diagnostic Log. | +| If something can't be read | When a check couldn't read everything (an integration was down), nothing is treated as gone, so a problem isn't called cleared just because its source couldn't be looked at. | + +The ticket says what is wrong, the severity, the kind, where it comes from, when it was first seen, and links back to the problem in this app. osTicket's +API can't update or close a ticket, so it isn't touched again: close it in osTicket when the problem is dealt with. Every ticket opened (and every test +ticket) is in the Audit Log as `alert_ticket`, and changes to the settings as `settings` / `update_alert_tickets`. "Send a test ticket" and "Check now" +on the settings page use the saved settings. ## What does *not* send a notification Worth calling out explicitly, since it's easy to assume everything in the app alerts on something: -- **osTicket** — the integration lists open tickets, but there is no - scheduled check or alert wired up for it (e.g. nothing pings you about - a newly-overdue ticket). It's a read-only dashboard/page today. +- **osTicket's own tickets** — the integration lists open tickets, but + there is no notification for it (e.g. nothing pings you about a + newly-overdue ticket); the page and the Alerts page show them. (The + other direction — an alert opening a ticket — is the section above.) - **phpIPAM sync**, **Uptime Kuma monitor/maintenance import**, and any other manual "Sync from X" action — these run when you click the button and report their result on the page itself, not via a diff --git a/README.md b/README.md index 7db7446..96a76c2 100644 --- a/README.md +++ b/README.md @@ -308,6 +308,14 @@ It checks live (a recent result is reused for a minute; "Check now" forces a fresh one), and anything it couldn't read is called out at the top rather than quietly treated as fine. +**Alert tickets** (Settings → Alert tickets, admin only) opens a ticket in osTicket for an alert, through osTicket's own API. Every 15 minutes the +problems on the Alerts page are looked at, and one that is new and has lasted two checks in a row gets one ticket — never a second for the same problem, +and never one for something under a maintenance window or about osTicket itself. You choose which severities and kinds count (critical and warning by +default), and the Alerts page shows the ticket number on each alert that has one. If many problems appear at once — a network drop that makes thirty +things look down — they become one summary ticket instead of thirty. Problems already there when you switch it on are left alone unless you ask for +tickets for them too. osTicket's API can't close or update a ticket, so once it's open it's yours to close. It needs an API key made in osTicket (tied to +this server's IP address, allowed to create tickets), entered on the osTicket integration; "Send a test ticket" checks the whole chain. + **Maintenance mode** silences alerts about one server, integration, or DNS provider while you work on it (server offline / disk, storage and Synology health, Proxmox backup alerts, Proxmox Backup Server verification alerts, and diff --git a/ROLES.md b/ROLES.md index 784e623..ff15065 100644 --- a/ROLES.md +++ b/ROLES.md @@ -82,6 +82,10 @@ even further, to admin only: - **Generator**: everyone can use it; the name lists it picks server names from are edited under Settings → Names, which is admin-only (and so is importing names from Skatteverket). +- **Alert tickets**: everyone sees which alerts have an osTicket ticket (a + badge on the Alerts page, linking to the ticket in osTicket); switching the + feature on, choosing what opens a ticket, and sending a test ticket are + under Settings → Alert tickets, which is admin-only. - Everything under **Settings** (notification channels, badge colors, display prefs, log retention, backup/restore) is admin-only, matching the page itself being admin-only.