From 5526a7f06851e279962aa168bb9dbec14dd29f4b Mon Sep 17 00:00:00 2001 From: MrAlders0n Date: Sun, 2 Aug 2026 08:00:07 -0400 Subject: [PATCH] docs(admin): document the repeater lifecycle & data cleanup settings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Groups every ageing/cleanup control into one "Repeater Lifecycle & Data Cleanup" section mirroring the panel's "Repeaters & Data Integrity" block, with a lifecycle-at-a-glance table and worked examples per setting: - Stale Repeater Age (and its two 3x rules) - Repeater Inactive After (newly configurable, was hardcoded 30d) - Repeater Retention / Auto-Delete — the clock runs from last advert heard, not from when the repeater went inactive, so the windows overlap; a sub-minimum value is rejected outright rather than clamped - Ghost Retention, and why ghosts are the evidence base for pending links - Pending Link Distance, incl. why the default is 200 km - Stale Ping Cleanup — the grace clock (picking a window does NOT delete the existing backlog), plus the Backfill Purge preview/confirm flow Also documents which settings a multi-region group controls vs. which stay per-region, the Pending Repeater Links alert (evidence tiers, the three choices, self-clearing suppression, the two refusal cases), the Suspicious Live Sessions alert, and the three new notification events. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KojjSrgSQQJW7Z8b3eakEA --- docs/admins.md | 311 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 298 insertions(+), 13 deletions(-) diff --git a/docs/admins.md b/docs/admins.md index ad373e2..919415b 100755 --- a/docs/admins.md +++ b/docs/admins.md @@ -36,7 +36,7 @@ Manage the repeaters database. - **Status Control:** - **Active:** The default state. The repeater is visible on the map, included in leaderboards, and actively associating with coverage pings. - **Disabled:** The repeater is hidden from the public map and leaderboards but remains in the database for historical purposes. - - **Inactive:** The repeater hasn't sent an advert in the last 30 days and has been removed from from the map. + - **Inactive:** The repeater hasn't sent an advert within the region's **Repeater Inactive After** window (default 30 days) and has been removed from the map. This is non-destructive — the record is retained and returns to Active automatically the next time the repeater is heard. See [Repeater Lifecycle & Data Cleanup](#repeater-lifecycle-data-cleanup). - **Pending:** The repeater has been discovered but is awaiting approval. Pending repeaters are **not** visible on the map and do not associate with coverage data. This state is only used when the "New Repeaters Enter Pending State" setting is enabled for the region. Admins can approve a pending repeater by editing it and setting its status to **Active**. Pending repeaters that have existed for 3× the stale timer will be automatically approved if still actively being heard, or deleted if not. - **Excluded:** The repeater is flagged as a duplicate. It appears as a **Red** icon on the map. Coverage data is **not** associated with this repeater to prevent skewing statistics (with the exception of **DISCOVERY** type pings). @@ -51,7 +51,7 @@ Manage the repeaters database. - **Neighbours Cleanup:** Reset the neighbours list for any repeater in the region. Useful for clearing stale or incorrect neighbour associations. - **Notes:** Clicking the note icon will allow you to optionally add a note to the repeater. On multiregion admin panels, if a repeater belongs to multiple single regions, notes will be combined and edits will be saved to the individual regions. - **Lock GPS Coordinates:** Enabling this setting will prevent new adverts from a repeater from updating its location. This can be used in instances where the GPS coordinates set on the repeater are incorrect and need to be manually overridden. - - **Bypass Auto Delete:** When enabled on a repeater, the automatic cleanup routines will skip it entirely. The repeater will not be set to inactive after 30 days, will not be deleted as a stale duplicate, and will not be removed as a stale pending repeater. This is useful for repeaters that are known to be offline for extended periods but should remain on the map (e.g. seasonal deployments, repeaters in remote locations with intermittent connectivity). + - **Bypass Auto Delete:** When enabled on a repeater, every automatic cleanup routine will skip it entirely. The repeater will not be marked inactive, will not be deleted as a stale duplicate, will not be removed as a stale pending repeater, and will not be removed by the [Repeater Retention / Auto-Delete](#repeater-retention-auto-delete-days) purge. This is useful for repeaters that are known to be offline for extended periods but should remain on the map (e.g. seasonal deployments, repeaters in remote locations with intermittent connectivity). - **Bulk Select & Edit/Delete:** Use the checkboxes on each row (or the "Select All" checkbox in the header) to select multiple repeaters. A toolbar will appear at the bottom of the screen with options to **Edit Selected** or **Delete Selected**. Bulk edit allows you to change Status, Power, Lock GPS, and Notes for all selected repeaters at once — each field has an "Apply" checkbox so you only change the fields you intend to. Works across multi-region admin panels. !!! warning "Bulk Notes" @@ -175,16 +175,13 @@ The **Tools** tab contains powerful utilities for bulk operations. **Use with ca Configure how the map behaves for your region. - - **Max Session Capacity**: Limit the number of simultaneous wardrivers to prevent mesh congestion. - - **Hide Companion Names**: Toggle privacy mode for the public map. - - **Stale Repeater Age**: Set how many hours without an advert before a repeater is considered stale and visually flagged on the map (default: 24 hours). This threshold also drives the automatic duplicate cleanup routine — a colliding repeater that has not been heard in **3× this value** is eligible for automatic deletion. For example, with a 12-hour stale age, stale duplicates are removed after 36 hours of silence. [See Duplicate Repeater IDs](https://wiki.meshmapper.net/duplicaterepeaterid/) - - **New Repeaters Enter Pending State**: When enabled, newly discovered repeaters will enter a **Pending** state instead of **Active**. Pending repeaters are hidden from the map until an admin reviews and approves them. After 3× the stale timer, pending repeaters are automatically approved if still actively being heard, or deleted if not. In multiregion mode, this setting is configured per-region under Region-Specific Settings. - - !!! warning "Data Inaccuracy Warning" - New repeaters will not display on the map until approved. This can cause data inaccuracies. Use with caution. +The Settings tab is organised into collapsible blocks. Everything that ages, hides, or deletes data lives together under **Repeaters & Data Integrity** — see [Repeater Lifecycle & Data Cleanup](#repeater-lifecycle-data-cleanup) below for the full walkthrough of those timers. + - **Max Session Capacity**: Limit the number of simultaneous wardrivers to prevent mesh congestion. + - **Disable All Flood Traffic**: Disables Active and Hybrid modes in the mobile app entirely — users in your region can only passively wardrive. When enabled, Max Session Capacity is forced to 0 and greyed out. + - **Hide Companion Names**: Toggle privacy mode for the public map. Also disables the companion filter for map traffic — the public map's Filter → User field is shown disabled with an explanation. - **Hop Bytes**: Configure the region's repeater identification byte length — 1-byte (256 IDs), 2-byte (65K IDs), or 3-byte (16M IDs). When set to 2 or 3-byte, companion devices connecting to wardrive sessions are automatically configured to use the enforced hop byte length. In 1-byte regions, MeshMapper passively detects which repeaters support multi-byte by watching packets and only confirmed repeaters will show multi-byte IDs on the map. Collision detection, coverage mapping, and leaderboards all respect the configured hop byte length. Changing the byte mode automatically recalculates repeater collisions and updates affected repeaters to Active status. Requires MeshCore firmware v1.14.0+. - - **Single Observer Mode**: Enable this if your region relies on a single MQTT ingestor to prevent repeaters from being flagged as "Stale" too quickly. This option prevents the repeater from displaying as stale and ultimately getting disabled at 30 days without an advert. + - **Single Observer Mode**: Enable this if your region relies on a single MQTT ingestor to prevent repeaters from being flagged as "Stale" too quickly. A region in Single Observer Mode is skipped entirely by the nightly repeater cleanup — repeaters are never marked stale, never marked inactive, and never auto-deleted. (Ghost cleanup still runs, since it only touches the heard-only catalog.) - **Public Channels**: Define which channels are treated as public traffic. - **Regions/Scopes**: If your region uses MeshCore Regions/Scopes, define it here. If not, leave the default scope of "*". - **Enforce Hybrid Mode**: Disables Active mode for wardrivers in your region. If your regions mesh has an issue with dropped packets due to high mesh traffic or many wardrivers, consider enabling this option. *(Mobile app functionality will be available with v1.1.0)* @@ -194,9 +191,256 @@ Configure how the map behaves for your region. - **Social Media Links**: Optionally add any number of social media or website links that will display on the "Region Info" window on your regions map. - **MQTT Observers**: Configure the list of letsmesh observers to ingest from. - **Subscribe to all local observers**: This gives a region the option to either define which observers make up their mesh and exclude everything else (when off), or by toggling this on, listen for packets from any connected observer in the IATA. Turning this off and defining which observers to use could be helpful in cases where someone has fired up an observer and connected it with an IATA, but in reality its far away from the actual region and not contributing to the mesh. - - **Disable Duplicate ID Detection Logic**: Allows the region to opt-out of MeshMapper's strict duplicate ID collision handling. When enabled, repeaters with colliding IDs will remain active, and pings will associate with all matching repeaters. - - *Warning:* This compromises data accuracy. A warning badge will be displayed on the public map, and the region will be excluded from global leaderboards. - - [Learn more about overriding duplicate detection](https://wiki.meshmapper.net/overrideduplicates/) + +### Repeater Lifecycle & Data Cleanup + +All of MeshMapper's ageing and cleanup controls are grouped together in the **Repeaters & Data Integrity** block of the Settings tab. They form a single pipeline: a repeater goes quiet, gets flagged, gets hidden, and — only if you opt in — eventually gets deleted. Each stage has its own timer, and each timer is independent of the others. + +The nightly cleanup job runs once per day across the whole fleet. Nothing here happens instantly when you save a setting; changes take effect on the next nightly run. + +#### The lifecycle at a glance + +Using the defaults, for a repeater that stops adverting at **day 0**: + +| Elapsed | What happens | Controlled by | +| --- | --- | --- | +| 24 hours | Flagged **stale** on the map. Still Active, still associates pings. | Stale Repeater Age (24h) | +| 72 hours (3×) | If it has a **colliding ID**, it becomes eligible for automatic deletion. If it is **Pending**, it is auto-approved (if still being heard) or deleted (if not). | Stale Repeater Age × 3 | +| 30 days | Marked **Inactive** and removed from the map. Non-destructive — the record stays in the database and returns to Active the moment it is heard again. | Repeater Inactive After (30 days) | +| Never (default) | Permanently deleted. **Off unless you set a retention value.** | Repeater Retention / Auto-Delete (blank) | + +Separately, and on their own clocks: + +| Data type | Default | Controlled by | +| --- | --- | --- | +| Heard-only "ghost" devices | Aged out after 30 days unheard | Ghost Retention | +| Orphaned coverage pings | Kept forever | Stale Ping Cleanup (Disabled) | + +#### Stale Repeater Age (Hours) + +**Default: 24. Always on. Non-destructive.** + +How many hours a repeater can go without sending an advert before it is considered stale and visually flagged on the map. A stale repeater is still Active — it still appears on the map and still associates with coverage pings. + +This value also drives two **3×** rules: + + - A repeater with a **colliding ID** that has not been heard in 3× this value becomes eligible for automatic deletion. [See Duplicate Repeater IDs](https://wiki.meshmapper.net/duplicaterepeaterid/) + - A **Pending** repeater that has existed for 3× this value is automatically approved if it is still being heard, or deleted if it is not. + +!!! example "Worked example" + Stale Repeater Age = **12** hours. + + - A repeater that last adverted 13 hours ago is flagged stale on the map. + - A duplicate-flagged repeater silent for 36 hours (3 × 12) is eligible for automatic duplicate cleanup. + - A pending repeater 36 hours old is auto-approved or deleted depending on whether it is still being heard. + + Lowering this value makes your map more responsive to outages but flags healthy repeaters more often in a quiet mesh. Raising it is the right call for regions with long advert intervals. + +#### Repeater Inactive After (Days) + +**Default: 30. Always on. Non-destructive.** + +How many days a repeater can go without an advert before it is marked **Inactive** (status 3) and removed from the map. + +This is fully reversible and loses nothing. The repeater row, its notes, its history, and its leaderboard contributions all stay in the database. The next time an advert arrives, ingestion flips it straight back to Active and it reappears on the map. + +Previously this was hardcoded to 30 days; it is now configurable per region. + +!!! example "Worked example" + A region with a slow, low-traffic mesh sets **Repeater Inactive After = 60**. A cottage-country repeater that only gets heard when someone drives past every few weeks now stays on the map for two months of silence instead of one. + + A dense urban region wanting a tighter map sets it to **14** — anything not heard in two weeks drops off, and reappears automatically if it comes back. + +!!! tip "Per-repeater override" + Enabling **Bypass Auto Delete** on an individual repeater (Repeaters tab) exempts it from *every* automatic routine described in this section — it will never be marked inactive, never deleted as a stale duplicate, never deleted as a stale pending repeater, and never deleted by the retention purge. Use it for seasonal or intentionally-offline deployments you want to keep pinned on the map. + +#### Repeater Retention / Auto-Delete (Days) + +**Default: blank (Disabled). Opt-in. DESTRUCTIVE.** + +!!! danger "This permanently deletes repeaters" + When set, a repeater that is **Inactive** and has not been heard for this many days is permanently deleted from your region's repeater database. Recovery is only possible from a nightly backup. **Leave the field blank to keep it disabled** — that is the default, and most regions should keep it that way. + +This is the only setting in the panel that removes registered repeaters. It exists for regions that accumulate large numbers of dead records — test devices, one-off hardware, repeaters that were replaced rather than moved — and want the database to stay clean without manual pruning. + +**How the clock is measured.** The deletion window is counted from the repeater's **last heard advert**, not from the day it flipped to Inactive. The two stages overlap on one timeline rather than running back to back. + +!!! example "Worked example" + Repeater Inactive After = **30**, Repeater Retention = **90**. + + A repeater last adverts on **January 1st**. + + - **January 31st** — 30 days silent. Marked Inactive, removed from the map. Record intact. + - **April 1st** — 90 days silent. Permanently deleted. + + So it sat Inactive and recoverable for **60 days** (90 − 30) before deletion, not 90. + + Set Retention = **30** with Inactive After = **30** instead, and the two coincide: the repeater is marked inactive and deleted on the same nightly run. + +**Minimum value.** The field enforces a live minimum — whichever is larger of your **Repeater Inactive After** value and a hard floor of **7 days**. The minimum shown next to the label updates as you type in the Inactive After field. A value below the minimum is rejected and the setting stays disabled, because a repeater cannot be deleted before it has been marked inactive. + +!!! example "Rejected values" + With Repeater Inactive After = **30**: + + - Retention = **90** → accepted. + - Retention = **30** → accepted (equal to the minimum). + - Retention = **20** → rejected, setting reverts to Disabled. + - Retention = **blank** → Disabled (the default). + +**What survives deletion.** Leaderboard points and Explorer credit earned against that repeater are preserved — they are moved to the **retired-points ledger** rather than lost, so no contributor's score drops because a repeater was cleaned up. The repeater row itself, however, is gone. + +**A second safety gate.** Even with a value set, nothing is deleted until the MeshMapper operator separately enables the fleet-wide purge flag on the server. Setting a retention value alone will not delete anything. + +Deletions are written to the audit log (repeater ID, last heard timestamp, and the retention window applied), so you can see exactly what was removed and when. + +#### Ghost Retention (Days) + +**Default: 30. Always on.** + +A **ghost** is a device MeshMapper has heard passively — it answered a wardriver's discovery ping — but which has never sent an advert. Because it never adverted, it carries no name and no fixed location, so it can never appear on the map as a repeater. Ghosts are tracked in a separate heard-only catalog, purely as evidence that *something* with that ID is transmitting in the area. + +This setting ages ghosts out of that catalog after the given number of days without being heard. + +Ghosts are also removed immediately — regardless of this timer — the moment the same ID becomes a **registered repeater** in your region. Once a device starts adverting, it is a real repeater and no longer needs a ghost entry, so the ghost record is dropped on the next nightly run. + +!!! info "Ghost cleanup never touches your repeaters" + This routine only prunes the heard-only catalog. It can never delete, hide, or modify a registered repeater. It also runs for regions in Single Observer Mode and for regions with no registered repeaters at all. + +**Why ghosts matter.** The ghost catalog is the evidence base for the **Pending Repeater Links** feature below. When a wardriver reports a repeater ID that resolves to a device hundreds of kilometres away, the presence of a local ghost sharing that ID is what tells you the pings almost certainly belong to an unregistered local device instead. Setting Ghost Retention too low weakens that evidence; setting it very high keeps stale ghosts around cluttering the analysis. + +!!! example "Worked example" + A wardriver drives past an unregistered repeater whose ID starts `C4A8`. It answers discovery 40 times but never adverts. + + - It is recorded as a ghost `C4A8…`, and is used as evidence in any pending-link decision involving that ID. + - With Ghost Retention = **30**, if nobody hears it again for 30 days the ghost entry is dropped. + - If its owner instead configures it properly and it starts adverting, it registers as a real repeater — and the ghost entry is deleted on the next nightly run, no waiting. + +#### Pending Link Distance (km) + +**Default: 200. Set to 0 to disable. Affects future ingestion only.** + +This is the guard against the "ghost repeater steals a distant repeater's pings" problem. + +When a wardriver hears a repeater, their radio reports a short ID token — often only one or two bytes. MeshMapper resolves that token against the registered repeater database. If the token resolves to exactly **one** registered repeater, MeshMapper would normally draw a link from the ping to that repeater's location. + +The failure case: an **unregistered** local repeater happens to share the same short ID as a registered repeater on the other side of the country. Without this check, every ping heard from the local device gets attributed to the distant one, drawing false coverage lines hundreds of kilometres long. + +**What this setting does:** if the single matching repeater sits farther than this many kilometres from the ping, the link is **not** drawn automatically. Instead the pings are held as a **Pending Repeater Link** in the Alerts tab for you to confirm or reject. The pings still appear on the map — they are simply not tied to a repeater until you decide. + +!!! example "Worked example" + Pending Link Distance = **200** (default). + + - A wardriver in Ottawa hears repeater token `C4`. It resolves uniquely to a repeater registered in Vancouver, **3,500 km away**. That is far past 200 km, so the pings are held for review and an alert appears. + - The same wardriver hears token `9F`, resolving to a repeater 40 km away on a nearby ridge. Well under 200 km — linked automatically, no alert. + - A mountaintop repeater genuinely reaching **215 km** would be held for review. You would use **Link to repeater** once, and future pings for that ID auto-link from then on. + +!!! question "Why 200 km?" + Genuine LoRa long-haul links (mountaintop to mountaintop) run up to roughly 220 km. Beyond that, a handheld radio in a car hearing a repeater almost always means the data actually belongs to an unregistered local device with a colliding short ID. The trade-off is deliberately asymmetric: a false alert costs you one click, while a missed one draws a permanently wrong line on the map. + +**Tuning it.** Lower the value in a geographically dense region where you know nothing legitimately reaches far — you will catch more collisions, at the cost of more alerts. Raise it if your region genuinely has extreme long-haul links and you are tired of confirming them. Set it to **0** to disable the check entirely and always auto-link. + +Changing this value affects **future ingestion only**. Existing pings and existing pending links are unaffected. + +See [Pending Repeater Links](#pending-repeater-links) under Alerts for how to actually resolve the alerts this generates. + +#### Stale Ping Cleanup (Auto-Delete Orphaned Pings) + +**Default: Disabled. Options: Disabled / 30 / 60 / 90 days. DESTRUCTIVE.** + +This ages out **orphaned** coverage pings. A ping is orphaned when the repeater it was attributed to has either **moved more than 100 m away** or **vanished from the database entirely** — exactly the pings the map already renders as **"(Gone)"**. + +A ping only counts as orphaned when *every* repeater association on it is gone. If any part of it still resolves to a live repeater at the right location, the ping is kept. The detector is deliberately conservative: any doubt keeps the row. + +##### The grace clock — the most important thing to understand + +**Choosing a window does not delete everything that is already that old.** This is the single most common misreading of this setting. + +Instead, the nightly job **starts a clock**. The first night it sees a ping orphaned, it stamps that ping with a timestamp. It only deletes the ping once it has stayed **continuously orphaned** for the full window. If the repeater comes back within 100 m at any point, the clock is cleared and the ping is kept. + +!!! example "Worked example — the grace clock" + You set Stale Ping Cleanup = **30 days** today, on **June 1st**. Your region has pings orphaned since **last year**. + + - **June 1st (tonight)** — the nightly job flags those pings as orphaned and stamps the clock. **Nothing is deleted.** + - **June 2nd–30th** — the job re-checks them each night. Still orphaned, clock keeps running. + - **July 1st** — 30 days continuously orphaned. *Now* they are deleted. + + So a ping orphaned for a year is still not deleted until 30 days after you turn the setting on. This is intentional: it gives a repeater that is only temporarily offline, or one that was accidentally deleted, a full window to come back before any data is lost. + +!!! example "Worked example — the clock resetting" + A repeater goes offline on **March 1st** and is deleted from the database on **March 5th**. Its pings become orphaned and the clock starts that night. + + - **March 20th** — the owner brings the repeater back and re-registers it at the same location. The pings resolve again, the clock is cleared, and nothing is deleted. + - Had it come back at a location **500 m away** instead, the pings would stay orphaned (>100 m) and the clock would keep running. + +##### What is preserved + +**Leaderboard points and Explorer credit are not lost.** Every deleted ping is written to the **retired-points ledger** before removal, inside the same transaction as the delete. Contributors keep their points, their grid-square "first" claims, and their portal statistics. Only the ping row itself is removed. + +##### Backfill Purge Now… + +The dropdown above ages pings out gradually. **Backfill Purge Now…** is the immediate one-time alternative — it does not wait out the clock. + +When you run it, it deletes every ping that is **already** orphaned **and** whose ping date is older than your saved retention window, plus any **no-location (0,0)** pings of any age. Recent orphaned coverage — anything inside the window — is deliberately kept, so a repeater that is only temporarily offline does not lose its data. + +The flow is: + + 1. Save a retention window (30 / 60 / 90) first. The preview will refuse to run without one. + 2. Click **Backfill Purge Now…**. A read-only preview modal opens. + 3. Review exactly what would be deleted — totals, a breakdown **by repeater** (with the reason each qualifies, e.g. *moved >100 m*), and a breakdown **by date** with ages. On a multi-region group you also get a per-region breakdown. + 4. Confirm. You must explicitly click through a confirmation showing the exact ping count. + +!!! example "Worked example — Backfill Purge" + Retention window = **30 days**. You run Backfill Purge on **June 1st**. + + - A ping from **January**, orphaned → **deleted** (already orphaned, older than 30 days). + - A ping from **May 25th**, orphaned → **kept** (only a week old, inside the window — the repeater may just be temporarily offline). + - A ping from **March** at coordinates **0,0** → **deleted** (no-location pings go regardless of age). + - A ping from **January** whose repeater is still live and within 100 m → **kept** (not orphaned at all). + + Use this to clear an existing backlog today rather than waiting for the nightly job to age each ping out individually. + +!!! warning "Minimum window for automatic sweeps" + The nightly automatic sweep refuses to run with an effective window under **30 days**, which is why the dropdown offers no shorter option. + +!!! info "Fleet rollout gate" + Like the repeater purge, real deletion is blocked fleet-wide until the MeshMapper operator enables it on the server. Until then, both the nightly job and the Backfill Purge button only *mark* pings — the preview still shows you accurately what will be removed once it is switched on, and the modal will tell you if you are in that state. + +If you have the **Ping Purge Cleanup Report** notification enabled, you will receive a Discord DM summarising what was removed. On a multi-region group this arrives as one combined message with a per-region breakdown. + +#### New Repeaters Enter Pending State + +When enabled, newly discovered repeaters will enter a **Pending** state instead of **Active**. Pending repeaters are hidden from the map until an admin reviews and approves them. After 3× the stale timer, pending repeaters are automatically approved if still actively being heard, or deleted if not. In multiregion mode, this setting is configured per-region under Region-Specific Settings. + +!!! warning "Data Inaccuracy Warning" + New repeaters will not display on the map until approved. This can cause data inaccuracies. Use with caution. + +#### Disable Duplicate ID Detection Logic + +Allows the region to opt-out of MeshMapper's strict duplicate ID collision handling. When enabled, repeaters with colliding IDs will remain active, and pings will associate with all matching repeaters. + + - *Warning:* This compromises data accuracy. A warning badge will be displayed on the public map, and the region will be excluded from global leaderboards. + - [Learn more about overriding duplicate detection](https://wiki.meshmapper.net/overrideduplicates/) + +#### Multi-region groups + +On a multiregion admin panel, these settings behave differently depending on where you set them. + +**Set at the group level** (Multi-Region Settings → Group Defaults) and applied to every member region: + + - Stale Repeater Age + - Pending Link Distance + - Stale Ping Cleanup (including Backfill Purge, which runs across every member region) + +**Set per-region**, on each member region's own settings: + + - Repeater Inactive After + - Repeater Retention / Auto-Delete + - Ghost Retention + +When you open a **member region** of a group, the group-controlled fields are shown greyed out and read-only — the group's value wins. Change them from the group panel instead. + +!!! info "How the value is resolved" + For each setting, MeshMapper checks the containing group's configuration first. If the group specifies a value, that value is used. If not, the region's own value is used. If neither sets one, the built-in default applies. ### Region Boundary @@ -222,8 +466,44 @@ The **User Settings** tab allows administrators to manage their own account. - **Repeater Clock Alerts**: Repeaters whose embedded timestamp differs from the server time by more than 120 seconds. An incorrect clock can affect packet routing and deduplication. - **Duplicate Repeater IDs** (Collisions): Multiple repeaters sharing the same short public ID. - **Pending Repeaters**: Repeaters awaiting approval (when "New Repeaters Enter Pending State" is enabled). + - **Pending Repeater Links**: Pings held for review because the repeater they resolve to is implausibly far away — see below. + - **Suspicious Live Sessions**: Sessions containing pings whose implied speed between consecutive fixes exceeds the flyover threshold — typically a device that was flown, or otherwise moved faster than any ground vehicle. Each row shows who, session ID, start time, peak speed, and ping count. You can **delete** the session to scrub the pings, or **dismiss** it if the movement was legitimately fast (a train, for example). Dismissed sessions are kept in a collapsed list so the decision is reviewable. - **History**: An audit log of all administrative actions (who edited what and when), ensuring accountability. +### Pending Repeater Links + +This alert is generated by the [Pending Link Distance](#pending-link-distance-km) setting. It appears when a wardriver's ping reports a repeater ID token that resolves to exactly one registered repeater, but that repeater sits farther away than your configured distance. + +The pings involved **stay on the map** — they are simply not tied to any repeater until you make a decision. Nothing is deleted, and nothing is hidden. + +#### Reading the evidence + +Each alert row is built to let you decide without leaving the page: + + - **The resolved repeater** — its ID, name, region, and how far away it is. + - **What was actually heard on-air** — the short token the wardriver's radio genuinely reported, which is often shorter than the resolved ID. This is the crux: the extra bytes came from MeshMapper's resolution, not from the radio. + - **Nearby ghosts** — unregistered devices that have answered discovery in this area, sorted into two tiers: + - **Strong matches**, whose key starts with the exact token that was heard. If one of these exists, the pings almost certainly belong to it rather than to the distant registered repeater. The panel will recommend leaving them unlinked. + - **Weak matches**, which share only the first byte. These are shown de-emphasised, because a wider heard token is what genuinely rules them out. + - **The held pings themselves** — expandable, showing date, session, the heard token, coordinates, and a **🗺️ Map** link that opens the public map at that exact ping. + +#### Your three choices + + - **Link to repeater** — you personally know that repeater genuinely reaches this area (a rare long-haul). The pings are linked using the repeater's current coordinates, the decision is recorded permanently, and future far pings for this ID auto-link. + - **Leave unlinked** — the likely case. The pings stay on the map, permanently marked as not tied to any repeater. New far pings for this ID will alert again. + - **Leave unlinked + suppress** — the same, but future far pings for this ID are quietly held without generating a new alert. Use this when you have confirmed there is a local unregistered device and you do not want repeat notifications. + +With more than one pending row, a **Suppress all** button appears. Suppressed IDs are listed in their own collapsible section with held-ping counts, and can be individually **Restored** or restored in bulk. + +!!! info "Suppression clears itself" + Suppression is not permanent. MeshMapper tracks the *situation* around each ID. The moment anything about it changes — a local repeater with that ID registers, the distant repeater moves or is deleted, or a new unregistered ghost appears in the area — the suppression is automatically cleared and you are alerted again. The same applies to a confirmed link. + +!!! warning "Two cases where linking is refused" + - **Unplaced repeater** — the repeater has no usable position (unplaced, or 0,0). It must be placed on the map before its links can be confirmed. This prevents pings being baked to a meaningless location. + - **Newly ambiguous** — more than one registered repeater now matches that ID, meaning the situation changed since the pings were held. Linking would be a guess between devices, so you are asked to review the ID's repeaters first. + +If a region has pending links awaiting review, a daily reminder is sent to admins who have the **Pending Repeater Link** notification enabled. Each ID notifies once; the latch resets if its situation changes. + ## Notifications Link your Discord to MeshMapper to receive DM's from the MeshMapper bot. @@ -232,5 +512,10 @@ Link your Discord to MeshMapper to receive DM's from the MeshMapper bot. - **Alert on Pending Repeater**: Once a day, receive a notification if your region has repeaters in **Pending** state that are awaiting review. This notification is only relevant if "New Repeaters Enter Pending State" is enabled for the region. - **Allow Messages From Visitors**: When enabled, a map visitor can send a message to you directly from the "Region Info" page of your regions map. - **Alert on Offline Observer**: Once a day (around 0800 EST/EDT) MeshMapper will review all data received via your regions MQTT observers (pings, repeater adverts, companion adverts) for the past 7 days. If a particular observer has sent data within that time, but not within the "Stale Repeater Age" time configured for your region, then this observer is potentially offline. Receive an alert when this is the case. + - **Suspicious Flight**: Receive an alert when a live session contains pings whose implied speed between consecutive fixes exceeds the flyover threshold — a device that was likely flown rather than driven. Corresponds to the **Suspicious Live Sessions** alert. + - **Pending Repeater Link**: Once a day, receive a summary of repeater IDs with pings held for review because they resolved to an implausibly distant repeater. Each ID notifies once; the latch resets automatically if the situation around that ID changes. See [Pending Repeater Links](#pending-repeater-links). + - **Ping Purge Cleanup Report**: Receive a DM summarising what the [Stale Ping Cleanup](#stale-ping-cleanup-auto-delete-orphaned-pings) removed — the ping count, and a breakdown by date and repeater. On a multiregion group this arrives as a single combined message with a per-region breakdown. Only sent when something was actually deleted. + +These events are also available as **webhook** subscriptions, configured separately in the Settings tab. See [Webhooks](https://wiki.meshmapper.net/webhooks/). Webhooks can also be configured per-region to send these same notifications to any HTTPS endpoint (Slack, Home Assistant, custom automation, etc.). See [Webhooks](https://wiki.meshmapper.net/webhooks) for setup instructions. \ No newline at end of file