diff --git a/.gitignore b/.gitignore
index 9e104b5..d3d6561 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
 # review pipeline scratch
 .diffcheck.php
 .rv.tar
+tests/_dbg.php
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa14bcb..8b3c8c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 ## Changelog
 
+--- 2.2 ---
+
+* Add IPv6 map and subnet drill-down support with filename-safe prefix tokens
+* Move hostname resolution to an asynchronous, last-known-good DNS cache
+* Surface active thold alarms on otherwise-up Device markers
+* Prune generated subnet artefacts after three poller intervals
+
 --- 2.1 ---
 
 * issue: Add gpsmap_templates table index to be unique by device template
diff --git a/INFO b/INFO
index 2b0f08a..229defe 100644
--- a/INFO
+++ b/INFO
@@ -1,6 +1,6 @@
 [info]
 name = gpsmap
-version = 2.1
+version = 2.2
 longname = Maps Plugin
 author = Andrew Aloia, Wixiweb, The Cacti Group
 email = 
diff --git a/README.md b/README.md
index 915acf5..9dfac0b 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,9 @@ Maps tab reads a static file instead of querying the database.
 
 ## Features
 
-* Devices plotted by latitude and longitude, coloured by Up, Recovering, Down,
-  Disabled or Undefined status
+* IPv4 and IPv6 Devices plotted by latitude and longitude, coloured by Up,
+  Recovering, Down, Disabled or Undefined status.  When thold is enabled, an
+  otherwise-up Device with an active threshold uses its Down icon
 
 * Per Device Template marker icons for the Up, Recovering and Down states
 
@@ -20,7 +21,7 @@ Maps tab reads a static file instead of querying the database.
   furthest Device sharing the Access Point's group number, and optionally
   limited to an arc
 
-* Drill down by subnet, from the first octet through to individual Devices
+* Drill down by subnet: /8, /16 and /24 for IPv4, and /16, /32 and /48 for IPv6
 
 * KML export alongside the XML, so the same data opens in Google Earth
 
@@ -55,8 +56,8 @@ JavaScript, and there is no workaround inside Cacti.
 
 Installing adds seven columns to Cacti's `host` table (`latitude`, `longitude`,
 `GPScoverage`, `start`, `stop`, `groupnum`, `rdistance`) and creates the
-`gpsmap_templates` table.  Uninstalling deliberately leaves both in place so
-coordinates survive an accidental removal.
+`gpsmap_templates` and `plugin_gpsmap_dns_cache` tables.  Uninstalling
+deliberately leaves them in place so coordinates survive an accidental removal.
 
 ## Configuration
 
@@ -139,13 +140,21 @@ Understanding the order of events explains most of what can go wrong.
 1. The poller runs and Cacti calls the plugin's `poller_bottom` hook.
 
 2. The plugin selects every Device whose Device Template appears in
-   `gpsmap_templates`, resolves each hostname to an address, and discards any
-   Device without coordinates or whose name does not resolve to IPv4.
+   `gpsmap_templates`.  Literal IPv4 and IPv6 addresses are used directly;
+   configured names use the last address in `plugin_gpsmap_dns_cache`.
 
 3. It writes `plugins/gpsmap/XML/all.xml`, `all.kml` and `all-top.html`, then
    repeats for each subnet prefix so the drill-down views are prebuilt.
 
-4. Opening the Maps tab serves a page that loads Google's map library and
+4. It starts a separate DNS refresh worker after publishing.  A newly configured
+   hostname can therefore appear on the following poll, while slow DNS never
+   holds up the poller.  A failed refresh retains the last-known address.
+
+5. Generated subnet files not refreshed for three poller intervals are removed.
+   Cleanup runs only after a successful Device query; unrelated files are never
+   touched.
+
+6. Opening the Maps tab serves a page that loads Google's map library and
    fetches the matching `.xml` file over HTTP.
 
 Nothing appears until a poll cycle has completed after configuration.  If
@@ -165,9 +174,14 @@ cycle has completed since both were set; and `plugins/gpsmap/XML` contains
 files newer than the last poll.
 
 **Some Devices are missing.**  A Device is skipped when it has no coordinates,
-when its hostname does not resolve to an IPv4 address, when its Device Template
-is not in Map Templates, or when it is disabled and Display Disabled Devices is
-off.
+when its hostname has no cached address yet, when its Device Template is not in
+Map Templates, or when it is disabled and Display Disabled Devices is off.  For
+a newly added hostname, allow one additional poll cycle for the asynchronous DNS
+worker to populate the cache.
+
+**An Up Device has a red marker.**  When the thold plugin is enabled, gpsmap
+uses the configured Down icon for an otherwise-up Device with any active,
+enabled threshold.  Disable or clear the threshold to restore the Up icon.
 
 **The XML directory is empty.**  The Data Collector cannot write to it.  Check
 ownership, permissions and SELinux context.  The Cacti log records a failure
diff --git a/gpsmap.php b/gpsmap.php
index d0fba7b..a328437 100644
--- a/gpsmap.php
+++ b/gpsmap.php
@@ -27,16 +27,17 @@
 
 general_header();
 
-//set headers to NOT cache a page
-header("Cache-Control: no-cache, no-store, must-revalidate");
-header("Pragma: no-cache");
-header("Expires: 0");
+// set headers to NOT cache a page
+header('Cache-Control: no-cache, no-store, must-revalidate');
+header('Pragma: no-cache');
+header('Expires: 0');
 
-//decide what needs to be shown
+// decide what needs to be shown
 switch ($show) {
-	//selected nodes
+	// selected nodes
 	case 'setup':
 		$body = __('Please make sure to properly configure Maps first under Settings > Maps', 'gpsmap');
+
 		break;
 	default:
 		if (!$parameter) {
@@ -46,44 +47,44 @@
 		/* Reject any parameter that contains directory traversal sequences or
 		 * characters outside the safe set.  basename() alone does not strip
 		 * embedded ../ so we validate the whole value first. */
-		if (!preg_match('/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$/', $parameter)) {
+		if (!preg_match('/^(?:all|[0-9]+(?:\.[0-9]+){0,2}|v6-(?:16-[0-9a-f]{4}|32-[0-9a-f]{8}|48-[0-9a-f]{12}))$/', $parameter)) {
 			$parameter = 'all';
 		}
 
 		$fileLocation = './plugins/gpsmap/XML/' . $parameter . '-top.html';
 
 		if (file_exists($fileLocation)) {
-			echo file_get_contents($fileLocation);
+			print file_get_contents($fileLocation);
 		}
 
 		break;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 
 if ($show != 'setup') { ?>
 	<script type='text/javascript'>
-		var initialLat      = <?php echo is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
-		var initialLng      = <?php echo is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
-		var initialZoom     = <?php echo json_encode((int) $initialzoom); ?>;
+		var initialLat      = <?php print is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
+		var initialLng      = <?php print is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
+		var initialZoom     = <?php print json_encode((int) $initialzoom); ?>;
 	</script>
 	<script type='text/javascript'>
-		gpsmap.refreshMap      = <?php echo json_encode((string) $refreshMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.initialLat      = <?php echo is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
-		gpsmap.initialLng      = <?php echo is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
-		gpsmap.initialZoom     = <?php echo json_encode((int) $initialzoom); ?>;
+		gpsmap.refreshMap      = <?php print json_encode((string) $refreshMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.initialLat      = <?php print is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
+		gpsmap.initialLng      = <?php print is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
+		gpsmap.initialZoom     = <?php print json_encode((int) $initialzoom); ?>;
 		gpsmap.initialized     = false;
-		gpsmap.liColor         = <?php echo json_encode((string) $liColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.liWidth         = <?php echo json_encode((string) $liWidth, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.liOpa           = <?php echo json_encode((string) $liOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.fillColor       = <?php echo json_encode((string) $fillColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.fillOpa         = <?php echo json_encode((string) $fillOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.circleQuality   = <?php echo json_encode((string) $circleQuality, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.enableWeather   = <?php echo json_encode((string) $enableWeather, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.coverageOverlay = <?php echo json_encode((string) $coverageMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liColor         = <?php print json_encode((string) $liColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liWidth         = <?php print json_encode((string) $liWidth, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liOpa           = <?php print json_encode((string) $liOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.fillColor       = <?php print json_encode((string) $fillColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.fillOpa         = <?php print json_encode((string) $fillOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.circleQuality   = <?php print json_encode((string) $circleQuality, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.enableWeather   = <?php print json_encode((string) $enableWeather, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.coverageOverlay = <?php print json_encode((string) $coverageMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
 		gpsmap.markerArray     = [];
-		gpsmap.downloadURL     = <?php echo json_encode($config['url_path'] . 'plugins/gpsmap/XML/' . $parameter . '.xml', JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.t_error         = <?php echo is_finite((float) $terror) ? json_encode((float) $terror) : '0'; ?>;
+		gpsmap.downloadURL     = <?php print json_encode($config['url_path'] . 'plugins/gpsmap/XML/' . $parameter . '.xml', JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.t_error         = <?php print is_finite((float) $terror) ? json_encode((float) $terror) : '0'; ?>;
 
 		<?php include_once('plugins/gpsmap/includes/icons.php'); ?>
 		<?php include_once('plugins/gpsmap/includes/customicons.php'); ?>
@@ -101,7 +102,6 @@
 <div id="mouse-position"></div>
 <div id="map"></div>
 ';
-echo $body;
+print $body;
 
 bottom_footer();
-
diff --git a/gpsmap_dns.php b/gpsmap_dns.php
new file mode 100644
index 0000000..d542770
--- /dev/null
+++ b/gpsmap_dns.php
@@ -0,0 +1,21 @@
+#!/usr/bin/env php
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+chdir(__DIR__ . '/../../');
+require_once('./include/cli_check.php');
+require_once($config['base_path'] . '/plugins/gpsmap/includes/dns.php');
+
+if (!register_process_start('gpsmap', 'dns-refresh', 0, 3600)) {
+	exit(0);
+}
+
+try {
+	gpsmap_refresh_dns_cache();
+} finally {
+	unregister_process('gpsmap', 'dns-refresh', 0);
+}
diff --git a/gpsmap_security.php b/gpsmap_security.php
index c740535..c8ae54a 100644
--- a/gpsmap_security.php
+++ b/gpsmap_security.php
@@ -38,3 +38,41 @@ function gpsmap_normalize_icon_name($value, $icon_array, $default = 'Green.png')
 
 	return $value;
 }
+
+//---------------------------------------------------------------
+function getIcons() {
+	$iconArray = array();
+	global $config;
+
+	/* Built from base_path so poller and CLI callers resolve it too; only web
+	 * entry points chdir() to the Cacti root. */
+	$dir = $config['base_path'] . '/plugins/gpsmap/images/icons';
+
+	/* Suppressed rather than warned: this runs on the Map Templates page, and a
+	 * missing icon folder should not print a PHP warning into the form. */
+	$icons = @opendir($dir);
+
+	if ($icons === false) {
+		return $iconArray;
+	}
+
+	while (false !== ($icon = readdir($icons))) {
+		/* Offer only names the map can actually render.  icons.php emits each
+		 * base name as a JavaScript identifier, so a file this rule rejects
+		 * would appear in the dropdown, save cleanly, and then silently fail
+		 * to draw. */
+		if (!in_array(strtolower(pathinfo($icon, PATHINFO_EXTENSION)), GPSMAP_ICON_EXTENSIONS, true)) {
+			continue;
+		}
+
+		if (gpsmap_icon_identifier($icon) === null) {
+			continue;
+		}
+
+		$iconArray[$icon] = $icon;
+	}
+
+	closedir($icons);
+
+	return $iconArray;
+}
diff --git a/gpstemplates.php b/gpstemplates.php
index ebc57ff..b913ebd 100644
--- a/gpstemplates.php
+++ b/gpstemplates.php
@@ -88,7 +88,7 @@ function templates() {
 			$url = $config['url_path'] . 'plugins/gpsmap/gpstemplates.php?action=edit&id=' . $template['templateID'];
 
 			form_alternate_row('line' . $template['templateID'], true);
-			form_selectable_cell("<a class='linkEditMain' href='$url'>" . html_escape($template['templateName']) . "</a>", $template['templateID']);
+			form_selectable_cell("<a class='linkEditMain' href='" . html_escape($url) . "'>" . html_escape($template['templateName']) . "</a>", $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['upimage']) . "'>", $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['recoverimage']) . "'>", $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['downimage']) . "'>", $template['templateID']);
@@ -252,29 +252,3 @@ function gpsmap_save_template() {
 }
 
 //------------------------------------------------------------------------------
-function getIcons() {
-	$iconArray = array();
-	$icons     = opendir('./plugins/gpsmap/images/icons');
-
-	while (false !== ($icon = readdir($icons))) {
-		if ($icon != '.' && $icon != '..') {
-			$iconExplode    = explode('.', $icon);
-			$iconExplode[1] = $iconExplode[1];
-
-			switch ($iconExplode[1]) {
-				case 'png':
-				case 'jpg':
-				case 'jpeg':
-				case 'gif':
-					$iconArray[$icon] = $icon;
-					break;
-				default:
-					break;
-			}
-		}
-	}
-
-	closedir($icons);
-
-	return $iconArray;
-}
diff --git a/includes/customicons.php b/includes/customicons.php
index 97a4aba..c09bff6 100644
--- a/includes/customicons.php
+++ b/includes/customicons.php
@@ -20,9 +20,9 @@
 */
 
 require_once(__DIR__ . '/../gpsmap_security.php');
-//This file takes care of the individual assignments for each custom icon set for the map templates
-//This pulls the template from MySQL and attaches the Up/Down/Recover icon reference.
-//Basically this makes a mapping between template and icon.
+// This file takes care of the individual assignments for each custom icon set for the map templates
+// This pulls the template from MySQL and attaches the Up/Down/Recover icon reference.
+// Basically this makes a mapping between template and icon.
 
 $customiconlist = "gpsmap.customIcons = {};\n";
 
@@ -32,7 +32,8 @@ function gpsmap_safe_icon_base(string $filename): string {
 	return gpsmap_icon_identifier($filename) ?? 'undefined';
 }
 
-$results = db_fetch_assoc_prepared('SELECT * FROM gpsmap_templates ORDER BY templateID', array());
+$results = db_fetch_assoc_prepared('SELECT * FROM gpsmap_templates ORDER BY templateID', []);
+
 if (cacti_sizeof($results)) {
 	foreach ($results as $row) {
 		$tid          = (int) $row['templateID'];
@@ -40,18 +41,19 @@ function gpsmap_safe_icon_base(string $filename): string {
 		$down_base    = gpsmap_safe_icon_base($row['downimage']);
 		$recover_base = gpsmap_safe_icon_base($row['recoverimage']);
 
-		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'up')        . '] = gpsmap.' . $up_base      . ";\n";
-		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'down')       . '] = gpsmap.' . $down_base    . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'up') . '] = gpsmap.' . $up_base . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'down') . '] = gpsmap.' . $down_base . ";\n";
 		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'recovering') . '] = gpsmap.' . $recover_base . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'alert') . '] = gpsmap.' . $down_base . ";\n";
 	}
 }
 
-//DO NOT REMOVE THESE
+// DO NOT REMOVE THESE
 $customiconlist .= "gpsmap.customIcons['up'] = gpsmap.Green;\n";
 $customiconlist .= "gpsmap.customIcons['recovering'] = gpsmap.Orange;\n";
+$customiconlist .= "gpsmap.customIcons['alert'] = gpsmap.Red;\n";
 $customiconlist .= "gpsmap.customIcons['down'] = gpsmap.Red;\n";
 $customiconlist .= "gpsmap.customIcons['disabled'] = gpsmap.Black;\n";
 $customiconlist .= "gpsmap.customIcons['undefined'] = gpsmap.Black;\n";
 
-echo $customiconlist;
-
+print $customiconlist;
diff --git a/includes/dns.php b/includes/dns.php
new file mode 100644
index 0000000..42a7626
--- /dev/null
+++ b/includes/dns.php
@@ -0,0 +1,59 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+function gpsmap_resolve_hostname(string $hostname, ?callable $lookup = null): string {
+	if (filter_var($hostname, FILTER_VALIDATE_IP)) {
+		return $hostname;
+	}
+
+	$lookup ??= static fn (string $name): array|false => dns_get_record($name, DNS_A | DNS_AAAA);
+	$records = @$lookup($hostname);
+
+	if (!is_array($records)) {
+		return '';
+	}
+
+	// Preserve the resolver's ordering; both families are valid map addresses.
+	foreach ($records as $record) {
+		$address = $record['ip'] ?? $record['ipv6'] ?? '';
+
+		if (filter_var($address, FILTER_VALIDATE_IP)) {
+			return $address;
+		}
+	}
+
+	return '';
+}
+
+function gpsmap_refresh_dns_cache(?callable $resolver = null): int {
+	$resolver ??= static fn (string $name): string => gpsmap_resolve_hostname($name);
+	$rows = db_fetch_assoc('SELECT DISTINCT h.hostname
+		FROM host AS h
+		INNER JOIN gpsmap_templates AS gt ON gt.templateID = h.host_template_id
+		LEFT JOIN plugin_gpsmap_dns_cache AS dc ON dc.hostname = h.hostname
+		WHERE dc.hostname IS NULL OR dc.refreshed_at < NOW() - INTERVAL 1 HOUR');
+
+	$updated = 0;
+
+	foreach ($rows ?: [] as $row) {
+		$hostname = (string) $row['hostname'];
+
+		if (filter_var($hostname, FILTER_VALIDATE_IP)) {
+			continue;
+		}
+
+		db_execute_prepared('INSERT INTO plugin_gpsmap_dns_cache
+			(hostname, address, refreshed_at) VALUES (?, ?, NOW())
+			ON DUPLICATE KEY UPDATE
+				address = IF(VALUES(address) = "", address, VALUES(address)),
+				refreshed_at = NOW()',
+			[$hostname, $resolver($hostname)]);
+		$updated++;
+	}
+
+	return $updated;
+}
diff --git a/includes/polling.php b/includes/polling.php
index 587abd8..5d6b92f 100644
--- a/includes/polling.php
+++ b/includes/polling.php
@@ -22,84 +22,61 @@
 function gpsmap_poller_bottom() {
 	global $config;
 
-	//Here we are getting the available hostnames (Numbers only) and
-	//Processing them to create our XML index arrays. So that it can
-	//pass an partial IP as a parameter to the region() function in
-	//the processregion.php file. Start with high subnet and work down.
 	include_once($config['base_path'] . '/plugins/gpsmap/includes/polling/functions.php');
+	include_once($config['base_path'] . '/plugins/gpsmap/includes/polling/pollinginitial.php');
+	include_once($config['base_path'] . '/plugins/gpsmap/includes/polling/processregion.php');
 
-	$result      =  db_fetch_assoc('SELECT hostname, latitude, longitude
-		FROM host AS h
-		INNER JOIN gpsmap_templates AS gt
-		ON h.host_template_id = gt.templateID');
+	$start = microtime(true);
 
-	$firstArray  = array();
-	$secondArray = array();
-	$thirdArray  = array();
-	$totals      = 0;
+	/* Load once.  Every subnet below is rendered from this same set, so the
+	 * device query and the DNS lookups happen a single time per poller cycle
+	 * rather than once per subnet. */
+	$hostArrays = gpsmap_load_devices(gpsmap_enable_all());
+	$mapped     = cacti_sizeof($hostArrays[0]) + cacti_sizeof($hostArrays[1]);
 
-	if (cacti_sizeof($result)) {
-		foreach($result as $row){
-			if ($row['latitude'] != '0.000' && $row['longitude'] != '0.000') {
-				$totals++;
+	/* Withhold publication only when the Device query itself failed.  An estate
+	 * with no mapped Devices is a real answer and has to be published, or a new
+	 * install never gets an all.xml at all and the map page fetches a 404. */
+	if (!empty($GLOBALS['gpsmap_load_failed'])) {
+		cacti_log('WARNING: gpsmap could not read the Device list this cycle; the existing map has been left in place', false, 'GPSMAP');
 
-				$hostname = gethostbyname($row['hostname']);
-
-				$indexes = explode('.', $hostname);
-
-				if (isset($indexes[0])) {
-					$first = $indexes[0];
-				} else {
-					$first = '';
-				}
-
-				if (isset($indexes[1])) {
-					$second = $indexes[1];
-				} else {
-					$second = '';
-				}
-
-				if (isset($indexes[2])) {
-					$third = $indexes[2];
-				} else {
-					$third = '';
-				}
+		return;
+	}
 
-				if (isset($indexes[3])) {
-					$fourth = $indexes[3];
-				} else {
-					$fourth = '';
-				}
+	if ($mapped === 0) {
+		cacti_log('NOTICE: gpsmap has no Devices to map.  Check that a Device Template is listed under Templates -> Map and that Devices have coordinates.', false, 'GPSMAP');
+	}
 
-				if (!in_array($first . '.', $firstArray)){
-					$firstArray[] = $first . '.';
-				}
+	$prefixes = gpsmap_subnet_prefixes($hostArrays);
 
-				if (!in_array($first . '.' . $second . '.', $secondArray)){
-					$secondArray[] = $first . '.' . $second . '.';
-				}
+	gpsmap_render_region($hostArrays, 'all');
 
-				if (!in_array($first . '.' . $second . '.' . $third . '.', $thirdArray)){
-					$thirdArray[] = $first . '.' . $second . '.' . $third . '.';
-				}
-			}
-		}
+	foreach ($prefixes as $prefix) {
+		gpsmap_render_region($hostArrays, $prefix);
 	}
 
-	callRegion('all');
-
-	if ($totals > 0) {
-		foreach($firstArray as $ip) {
-			callRegion($ip);
-		}
+	/* Only a successful cycle may age out old snapshots. Three poller intervals
+	 * make absence persistent evidence instead of a transient partial result. */
+	$poller_interval = max(60, (int) read_config_option('poller_interval'));
+	$pruned          = gpsmap_prune_artifacts(time() - (3 * $poller_interval));
 
-		foreach($secondArray as $ip) {
-			callRegion($ip);
-		}
+	/* DNS refresh is deliberately a separate process. This poll uses literals
+	 * and last-known cached values, then asks the background worker to refresh
+	 * names for a future cycle. */
+	if (db_table_exists('plugin_gpsmap_dns_cache') && function_exists('exec_background')) {
+		$php = read_config_option('path_php_binary');
 
-		foreach($thirdArray as $ip) {
-			callRegion($ip);
+		if ($php !== '') {
+			exec_background($php, $config['base_path'] . '/plugins/gpsmap/gpsmap_dns.php');
 		}
 	}
-}
 
+	cacti_log(sprintf(
+		'GPSMAP STATS: Mapped:%d Towers:%d Subnets:%d Pruned:%d Time:%0.2f',
+		$mapped,
+		cacti_sizeof($hostArrays[0]),
+		cacti_sizeof($prefixes),
+		$pruned,
+		microtime(true) - $start
+	), false, 'GPSMAP');
+}
diff --git a/includes/polling/functions.php b/includes/polling/functions.php
index d1b158f..0a3fc26 100644
--- a/includes/polling/functions.php
+++ b/includes/polling/functions.php
@@ -20,7 +20,7 @@
 */
 
 require_once(__DIR__ . '/../../gpsmap_security.php');
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function callRegion(string $subnet): void {
 	global $config;
 
@@ -30,18 +30,18 @@ function callRegion(string $subnet): void {
 	region($subnet);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function getTowerIds(): array {
 	$results = db_fetch_assoc_prepared('SELECT `templateID`
 		FROM `gpsmap_templates`
-		WHERE `AP` = 1', array());
+		WHERE `AP` = 1', []);
 
 	/* 9999 is a sentinel that matches no host_template_id, so an empty
 	 * result set still produces a usable in_array() haystack. */
-	return cacti_sizeof($results) ? array_column($results, 'templateID') : array(9999);
+	return cacti_sizeof($results) ? array_column($results, 'templateID') : [9999];
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Returns the great-circle distance in kilometres (not metres, the constant
  * 6378.7 is Earth's mean radius in km).  Renamed from calcMeters to reflect
  * the actual unit; callers treating the result as metres will be off by 1000x.
@@ -58,15 +58,15 @@ function calcMeters(float $Lat1, float $Lon1, float $Lat2, float $Lon2): float {
 	return calcKm($Lat1, $Lon1, $Lat2, $Lon2);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function coordCheck(string $coords): string {
 	$coords = trim($coords);
 
-	//return 0.000 for anything unparseable, the user can correct the device
+	// return 0.000 for anything unparseable, the user can correct the device
 	return preg_match('#^-?\d{1,3}\.\d+$#', $coords) ? $coords : '0.000';
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Single writer for every generated artefact (XML, KML, top HTML) so the
  * failure path and its log message stay identical across all three. */
 function gpsmap_write_file(string $filename, string $contents): bool {
@@ -80,6 +80,10 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 	 * poller rewrites them, and rename() is atomic within a filesystem.  A
 	 * short write is a failure, so disk pressure cannot publish a truncated
 	 * document while reporting success. */
+	/* The temp file is a new inode, so it starts at 0666 & ~umask rather than
+	 * inheriting the destination's mode.  These files are read by the web
+	 * server, not the poller, so losing the mode breaks the map silently. */
+	$mode = file_exists($filename) ? (fileperms($filename) & 0777) : 0;
 	$temp = $filename . '.' . getmypid() . '.tmp';
 	$f    = @fopen($temp, 'w');
 
@@ -95,6 +99,14 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 		return $fail();
 	}
 
+	/* rename() already replaces an existing destination on every supported
+	 * platform, so a failure here is a filesystem or permission problem.
+	 * Unlinking first would destroy the last-good document without any
+	 * guarantee the retry succeeds, turning a stale map into a missing one. */
+	if ($mode !== 0) {
+		@chmod($temp, $mode);
+	}
+
 	if (!@rename($temp, $filename)) {
 		@unlink($temp);
 
@@ -104,20 +116,97 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 	return true;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function gpsmap_xml_path(string $preemptive, string $extension): string {
 	global $config;
 
-	return $config['base_path'] . '/plugins/gpsmap/XML/' . trim($preemptive, '.') . '.' . $extension;
+	return $config['base_path'] . '/plugins/gpsmap/XML/' . gpsmap_artifact_stem($preemptive) . '.' . $extension;
+}
+
+// ---------------------------------------------------------------
+/* IPv4 keeps its historical dotted tokens.  IPv6 uses a reversible, filename
+ * safe token: v6-<prefix length>-<significant hex>. */
+function gpsmap_ipv6_prefix_token(string $address, int $length): ?string {
+	$packed = @inet_pton($address);
+
+	if ($packed === false || strlen($packed) !== 16 || !in_array($length, [16, 32, 48], true)) {
+		return null;
+	}
+
+	return 'v6-' . $length . '-' . substr(bin2hex($packed), 0, intdiv($length, 4));
+}
+
+// ---------------------------------------------------------------
+function gpsmap_ipv6_prefix_label(string $token): ?string {
+	if (!preg_match('/^v6-(16|32|48)-([0-9a-f]+)$/', $token, $matches)) {
+		return null;
+	}
+
+	$length = (int) $matches[1];
+
+	if (strlen($matches[2]) !== intdiv($length, 4)) {
+		return null;
+	}
+
+	$packed = hex2bin(str_pad($matches[2], 32, '0'));
+
+	return inet_ntop($packed) . '/' . $length;
+}
+
+// ---------------------------------------------------------------
+function gpsmap_ipv6_prefix_contains(string $token, string $address): bool {
+	if (!preg_match('/^v6-(16|32|48)-([0-9a-f]+)$/', $token, $matches)) {
+		return false;
+	}
+
+	if (strlen($matches[2]) !== intdiv((int) $matches[1], 4)) {
+		return false;
+	}
+
+	$packed = @inet_pton($address);
+
+	return $packed !== false && strlen($packed) === 16 && str_starts_with(bin2hex($packed), $matches[2]);
+}
+
+// ---------------------------------------------------------------
+function gpsmap_artifact_stem(string $subnet): string {
+	$subnet = $subnet === '' ? 'all' : trim($subnet, '.');
+
+	return preg_match('/^(?:all|[0-9]+(?:\.[0-9]+){0,2}|v6-(?:16-[0-9a-f]{4}|32-[0-9a-f]{8}|48-[0-9a-f]{12}))$/', $subnet)
+		? $subnet
+		: 'all';
+}
+
+// ---------------------------------------------------------------
+function gpsmap_prune_artifacts(int $olderThan): int {
+	global $config;
+
+	$directory = $config['base_path'] . '/plugins/gpsmap/XML';
+	$removed   = 0;
+
+	foreach (glob($directory . '/*') ?: [] as $path) {
+		$name = basename($path);
+
+		if (!is_file($path) || filemtime($path) >= $olderThan ||
+			!preg_match('/^(?:all|[0-9]+(?:\.[0-9]+){0,2}|v6-(?:16-[0-9a-f]{4}|32-[0-9a-f]{8}|48-[0-9a-f]{12}))(?:\.xml|\.kml|-top\.html)$/', $name)) {
+			continue;
+		}
+
+		if (@unlink($path)) {
+			$removed++;
+		}
+	}
+
+	return $removed;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function createDoc(array $hostArrays, string $preemptive): void {
 	xmlCreate($hostArrays, $preemptive);
 	kmlCreate($hostArrays, $preemptive);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* The previous implementation processed '&' last, which re-encoded the '&'
  * already introduced by the earlier substitutions (e.g. '<' -> '&lt;' -> '&amp;lt;').
  * htmlspecialchars() with ENT_XML1 handles the correct order atomically. */
@@ -125,7 +214,7 @@ function parseToXML($htmlStr): string {
 	return htmlspecialchars((string) $htmlStr, ENT_XML1 | ENT_QUOTES, 'UTF-8');
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function xmlCreate(array $hostArrays, string $preemptive): void {
 	$doc = '<markers>'
 		. createXMLNodes($hostArrays[1])
@@ -135,7 +224,7 @@ function xmlCreate(array $hostArrays, string $preemptive): void {
 	gpsmap_write_file(gpsmap_xml_path($preemptive, 'xml'), $doc);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function coverageXML(array $hostArrays): string {
 	global $config;
 
@@ -145,19 +234,19 @@ function coverageXML(array $hostArrays): string {
 	return $doc;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function kmlCreate(array $hostArrays, string $preemptive): void {
 	global $config;
 
 	require($config['base_path'] . '/plugins/gpsmap/includes/polling/kmlcreation.php');
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function createTypeArray(): array {
-	return array_column(db_fetch_assoc_prepared('SELECT `id`, `name` FROM `host_template`', array()), 'name', 'id');
+	return array_column(db_fetch_assoc_prepared('SELECT `id`, `name` FROM `host_template`', []), 'name', 'id');
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Renders one <marker/>.  Device markers carry no radius and no schedule;
  * tower markers carry the computed coverage radius and their active window. */
 function gpsmap_marker(host $host, array $typeArray, string $radius, bool $withSchedule): string {
@@ -182,7 +271,7 @@ function gpsmap_marker(host $host, array $typeArray, string $radius, bool $withS
 	return $doc . 'group="' . parseToXML($host->group) . '" />' . "\n";
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function createXMLNodes(array $hostArray): string {
 	$typeArray = createTypeArray();
 	$doc       = '';
diff --git a/includes/polling/kmlcreation.php b/includes/polling/kmlcreation.php
index e920575..31f8b39 100644
--- a/includes/polling/kmlcreation.php
+++ b/includes/polling/kmlcreation.php
@@ -30,7 +30,7 @@
 $kmldoc .= '<name>Map Points</name>' . "\n";
 $kmldoc .= iconskml();
 
-//fallback style for any placemark whose icon is not in the icon folder
+// fallback style for any placemark whose icon is not in the icon folder
 $kmldoc .= '<Style id="pushpin">'
 	. '<IconStyle id="mystyle">'
 	. '<Icon>'
@@ -42,8 +42,13 @@
 
 foreach ($hostArrays as $hostArray) {
 	foreach ($hostArray as $host) {
+		if ($host->showMap !== 1) {
+			continue;
+		}
+
 		$image = match ($host->status) {
-			'down'       => $host->downimage,
+			'down',
+			'alert'      => $host->downimage,
 			'recovering' => $host->recoverimage,
 			default      => $host->upimage,
 		};
diff --git a/includes/polling/processregion.php b/includes/polling/processregion.php
index 3ad8e7c..e8b691c 100644
--- a/includes/polling/processregion.php
+++ b/includes/polling/processregion.php
@@ -19,65 +19,95 @@
  +-------------------------------------------------------------------------+
 */
 
-//this function is called to process the nodes and get them ready for analysis
-//---------------------------------------------------------------
+/* The poller renders one file set per subnet prefix.  Loading the device list
+ * is the expensive part -- one query plus a DNS lookup per device -- so it
+ * happens once in gpsmap_load_devices() and every render reuses the result.
+ * region() keeps the old load-then-render shape for single callers. */
+
+// ---------------------------------------------------------------
 function region(string $subnet): void {
-	global $config;
+	$hostArrays = gpsmap_load_devices(gpsmap_enable_all());
+
+	gpsmap_render_region($hostArrays, $subnet);
+}
 
-	/* Read the setting here rather than through a global.  pollinginitial.php
-	 * assigns $enableAll, but it is include_once'd from inside callRegion(), so
-	 * the assignment binds to that function's scope and the global was always
-	 * null: the setting has never taken effect.  Cacti's checkbox convention is
-	 * 'on' when ticked and '' otherwise. */
-	$enableAll = (read_config_option('gpsmap_enableall') === 'on');
-	$towerIds  = getTowerIds();
+// ---------------------------------------------------------------
+/* One query and no synchronous DNS. Returns array(towers, devices) in the
+ * order coveragexml.php and xmlCreate() expect. */
+function gpsmap_enable_all(): bool {
+	/* pollinginitial.php assigns $enableAll from inside callRegion(), so the
+	 * global that used to be read here was never bound and the setting was
+	 * inert.  Read it where it is needed instead. */
+	return read_config_option('gpsmap_enableall') === 'on';
+}
+
+// ---------------------------------------------------------------
+function gpsmap_load_devices(bool $enableAll): array {
+	global $config;
 
 	include_once($config['base_path'] . '/plugins/gpsmap/class/hosts_class.php');
 
-	/* Per-call output.  This used to be a global that region() had to blank on
-	 * the way out; the poller calls region() once per subnet, so a missed reset
-	 * concatenated every earlier subnet's navigation into the next file. */
-	$body       = '';
-	$kmlDomain  = read_config_option('base_url');
-	$iparray    = array();
-	$ipwriteout = array();
-	$hostArray  = array();
-	$towerArray = array();
+	$towerIds = getTowerIds();
 
-	/* Select only the columns used by region()/createDoc().  Avoids pulling
-	 * SNMP credentials (snmp_community, snmp_auth_passphrase, etc.) into PHP
+	/* Select only the columns used by the renderers.  Avoids pulling SNMP
+	 * credentials (snmp_community, snmp_auth_passphrase, etc.) into PHP
 	 * memory on every poller cycle. */
-	$sql = 'SELECT h.id, h.host_template_id, h.hostname, h.description,
+	$has_dns   = db_table_exists('plugin_gpsmap_dns_cache');
+	$has_thold = api_plugin_is_enabled('thold') && db_table_exists('thold_data');
+	$sql       = 'SELECT h.id, h.host_template_id, h.hostname, h.description,
 		h.status, h.disabled, h.availability, h.cur_time,
 		h.latitude, h.longitude, h.start, h.stop, h.rdistance,
 		h.groupnum, h.GPScoverage,
-		gt.AP, gt.upimage, gt.downimage, gt.recoverimage
+		gt.AP, gt.upimage, gt.downimage, gt.recoverimage'
+		. ($has_dns ? ', dc.address AS cached_address' : ', NULL AS cached_address')
+		. ($has_thold ? ', COALESCE(td.thold_alarm, 0) AS thold_alarm' : ', 0 AS thold_alarm') . '
 		FROM `host` AS h
 		INNER JOIN gpsmap_templates AS gt
-		ON h.host_template_id = gt.templateID';
-
-	/* Cacti stores '' for enabled and 'on' for disabled. */
+		ON h.host_template_id = gt.templateID'
+		. ($has_dns ? '
+		LEFT JOIN plugin_gpsmap_dns_cache AS dc ON dc.hostname = h.hostname' : '')
+		. ($has_thold ? '
+		LEFT JOIN (
+			SELECT host_id, MAX(thold_alert > 0) AS thold_alarm
+			FROM thold_data
+			WHERE thold_enabled = "on"
+			GROUP BY host_id
+		) AS td ON td.host_id = h.id' : '');
+
+	// Cacti stores '' for enabled and 'on' for disabled.
 	$sql_where  = $enableAll ? '' : ' WHERE h.disabled = ?';
-	$sql_params = $enableAll ? array() : array('');
+	$sql_params = $enableAll ? [] : [''];
 
 	$results = db_fetch_assoc_prepared($sql . $sql_where . ' ORDER BY h.hostname', $sql_params);
 
-	/* Cache hostname -> IP resolutions so each hostname is resolved at most
-	 * once per region() call rather than twice (here and in the subnet loop).
-	 * Intentionally per-invocation with no TTL: the poller is batch-oriented
-	 * and stale entries within a single cycle are acceptable. If poller cycles
-	 * exceed 5 minutes, consider adding a TTL-based expiry. */
-	$dns_cache = array();
+	/* A failed query and an estate with no mapped Devices both arrive here as
+	 * an empty set.  Only the first is a reason to withhold publication, so the
+	 * caller is told which happened.
+	 *
+	 * false really is reachable: db_fetch_assoc_prepared() delegates to
+	 * db_execute_prepared(), which returns false on a connection failure, a
+	 * failed re-connect and an exhausted retry loop, and db_fetch_assoc_return()
+	 * documents itself as returning "the associated array of data, or false on
+	 * failure" (Cacti 1.2.x lib/database.php). */
+	$GLOBALS['gpsmap_load_failed'] = ($results === false);
+
+	$towerArray = [];
+	$hostArray  = [];
+
+	if (!cacti_sizeof($results)) {
+		return [$towerArray, $hostArray];
+	}
 
 	foreach ($results as $row) {
 		if ($row['latitude'] == '0.000' || $row['longitude'] == '0.000') {
 			continue;
 		}
 
-		$dns_cache[$row['hostname']] ??= gethostbyname($row['hostname']);
-		$hostip = $dns_cache[$row['hostname']];
+		/* Literal addresses need no DNS.  Names use the last asynchronously
+		 * refreshed cache value; the poller never blocks on a resolver. */
+		$hostip = is_ipaddress($row['hostname']) ? $row['hostname'] : ($row['cached_address'] ?? '');
 
-		if (!is_ipaddress($hostip) || substr_count($hostip, '.') != 3) {
+		if (!is_ipaddress($hostip)) {
 			continue;
 		}
 
@@ -90,9 +120,11 @@ function region(string $subnet): void {
 
 		if ($row['disabled'] == 'on') {
 			$status = 'disabled';
+		} elseif ($status === 'up' && !empty($row['thold_alarm'])) {
+			$status = 'alert';
 		}
 
-		$is_tower = in_array($row['host_template_id'], $towerIds);
+		$is_tower = in_array($row['host_template_id'], $towerIds, true);
 
 		$host = new host(
 			$row['id'],
@@ -110,7 +142,7 @@ function region(string $subnet): void {
 			$row['upimage'] ?: 'Green',
 			$row['downimage'] ?: 'Red',
 			$row['recoverimage'] ?: 'Yellow',
-			/* Only towers carry a coverage window; devices use the full day. */
+			// Only towers carry a coverage window; devices use the full day.
 			$is_tower ? $row['start'] : '0',
 			$is_tower ? $row['stop'] : '360',
 			$row['groupnum'],
@@ -123,29 +155,114 @@ function region(string $subnet): void {
 		}
 	}
 
-	$hostArrays = array($towerArray, $hostArray);
-	$preempt    = ($subnet == 'all') ? 0 : str_word_count($subnet, 0, '.');
+	return [$towerArray, $hostArray];
+}
 
-	//This section deals with traversal of the subnets
-	//sort by top level, and display all top IP range so they can be selected, and iterate this down through level 4
-	//if subnet level is met we want to display the lower ones.
-	//for 1 we want to display all top level IP
+// ---------------------------------------------------------------
+/* Rendering mutates showMap and grows tower radii, so the shared device set
+ * has to be returned to its loaded state before each subnet. */
+function gpsmap_reset_devices(array $hostArrays): void {
 	foreach ($hostArrays as $group) {
 		foreach ($group as $host) {
-			$dns_cache[$host->hostname] ??= gethostbyname($host->hostname);
+			$host->showMap = 1;
+			$host->radius  = '0';
+		}
+	}
+}
+
+// ---------------------------------------------------------------
+/* Every distinct /8, /16 and /24 prefix present in the loaded device set.
+ * Derived from the already-resolved addresses, so no second DNS pass. */
+function gpsmap_subnet_prefixes(array $hostArrays): array {
+	/* Keyed rather than searched: in_array() over a growing list is quadratic in
+	 * the number of prefixes, which is material on a large estate. */
+	$prefixes = [];
+
+	foreach ($hostArrays as $group) {
+		foreach ($group as $host) {
+			if (filter_var($host->iprange, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
+				for ($depth = 1; $depth <= 3; $depth++) {
+					$token = gpsmap_ipv6_prefix_token($host->iprange, $depth * 16);
+
+					if ($token !== null) {
+						$prefixes[$token] = true;
+					}
+				}
+
+				continue;
+			}
+
+			$octets = array_pad(explode('.', $host->iprange), 4, '0');
+
+			for ($depth = 1; $depth <= 3; $depth++) {
+				$prefixes[implode('.', array_slice($octets, 0, $depth)) . '.'] = true;
+			}
+		}
+	}
+
+	return array_keys($prefixes);
+}
+
+// ---------------------------------------------------------------
+function gpsmap_render_region(array $hostArrays, string $subnet): void {
+	global $config;
+
+	gpsmap_reset_devices($hostArrays);
+
+	$kmlDomain  = read_config_option('base_url');
+	$body       = '';
+	$iparray    = [];
+	$ipwriteout = [];
+	$subnet     = $subnet === '' ? 'all' : $subnet;
+	$is_all     = $subnet === 'all';
+	$is_v6      = str_starts_with($subnet, 'v6-');
+	$preempt    = $is_all ? 0 : ($is_v6 ? (int) explode('-', $subnet, 3)[1] / 16 : str_word_count($subnet, 0, '.'));
+
+	// This section deals with traversal of the subnets
+	// sort by top level, and display all top IP range so they can be selected, and iterate this down through level 4
+	// if subnet level is met we want to display the lower ones.
+	// for 1 we want to display all top level IP
+	foreach ($hostArrays as $group) {
+		foreach ($group as $host) {
+			$host_is_v6 = filter_var($host->iprange, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6) !== false;
+
+			if ($is_v6 || ($is_all && $host_is_v6)) {
+				if (!$host_is_v6 || (!$is_all && !gpsmap_ipv6_prefix_contains($subnet, $host->iprange))) {
+					$host->showMap = 0;
+
+					continue;
+				}
+
+				$child = gpsmap_ipv6_prefix_token($host->iprange, ($preempt + 1) * 16);
+
+				if ($preempt === 3) {
+					if (!in_array($host->iprange, $iparray, true)) {
+						$iparray[]    = $host->iprange;
+						$ipwriteout[] = '<a href="' . $config['url_path'] . 'graph_view.php?action=preview&amp;reset=1&amp;host_id=' . $host->id . '">' . __('IP %s', html_escape($host->iprange), 'gpsmap') . '</a><br/>';
+					}
+				} elseif ($child !== null && !in_array($child, $iparray, true)) {
+					$iparray[] = $child;
+				}
+
+				continue;
+			}
+
+			if ($host_is_v6) {
+				$host->showMap = 0;
+
+				continue;
+			}
 
-			/* pad to 4 elements so destructuring is safe when the name did not
-			 * resolve to a dotted-quad. */
-			[$first, $second, $third, $fourth] = array_pad(explode('.', $dns_cache[$host->hostname]), 4, '0');
+			// iprange is the address gpsmap_load_devices() already resolved.
+			$octets = array_pad(explode('.', $host->iprange), 4, '0');
 
 			/* The prefix this host would contribute at the current depth, and
 			 * the prefix the requested subnet has to match for it to count. */
-			$octets = array($first, $second, $third, $fourth);
 			$parent = implode('.', array_slice($octets, 0, $preempt)) . '.';
 			$child  = implode('.', array_slice($octets, 0, $preempt + 1)) . '.';
 
 			if ($preempt > 3 || ($preempt > 0 && strcasecmp($subnet, $parent) !== 0)) {
-				//outside the requested subnet, keep it off the map
+				// outside the requested subnet, keep it off the map
 				$host->showMap = 0;
 
 				continue;
@@ -157,41 +274,42 @@ function region(string $subnet): void {
 				 * two Devices resolving to one address each emit a link. */
 				$leaf = rtrim($child, '.');
 
-				if (!in_array($leaf, $iparray)) {
+				if (!in_array($leaf, $iparray, true)) {
 					$iparray[]    = $leaf;
 					$ipwriteout[] = '<a href="' . $config['url_path'] . 'graph_view.php?action=preview&reset=1&host_id=' . $host->id . '">' . __('IP %s', $leaf) . '</a><br/>';
 				}
-			} elseif (!in_array($child, $iparray)) {
+			} elseif (!in_array($child, $iparray, true)) {
 				$iparray[] = $child;
 			}
 		}
 	}
 
-	//process data collected and create interface output
+	// process data collected and create interface output
 	if ($preempt != 3) {
 		foreach ($iparray as $ipout) {
-			$ipout = trim($ipout, '.');
+			$token = trim($ipout, '.');
+			$label = gpsmap_ipv6_prefix_label($token) ?? $token;
 
-			$ipwriteout[] = '<a href="' . html_escape($config['url_path'] . 'plugins/gpsmap/gpsmap.php?subnet=' . $ipout) . '">' . __('IP %s', $ipout, 'gpsmap') . '</a>-(<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $ipout . '.xml">X</a>-<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $ipout . '.kml">K</a>)<br/>';
+			$ipwriteout[] = '<a href="' . html_escape($config['url_path'] . 'plugins/gpsmap/gpsmap.php?subnet=' . rawurlencode($token)) . '">' . __('IP %s', html_escape($label), 'gpsmap') . '</a>-(<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $token . '.xml">X</a>-<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $token . '.kml">K</a>)<br/>';
 		}
 	}
 
-	//print out the information we have gathered.
+	// print out the information we have gathered.
 	$body .= '<div id="gpstopmenu" style="overflow: auto; width:100%; ">';
 	$body .= '<div id="gpsnav" style="overflow:auto; float:left; position:relative;"><input type="button" value="' . __esc('Start Over', 'gpsmap') . '" onclick="window.location.reload(true);" />';
 	$body .= '<input type="button" class="print" alt="" value="' . __esc('Print', 'gpsmap') . '" onclick="window.open(\'print.php\')" />';
 	$body .= '</div>';
 
-	//six links per column block
+	// six links per column block
 	foreach (array_chunk($ipwriteout, 6) as $chunk) {
 		$body .= '<div id="iplevels" style="display:table-cell;vertical-align:middle;overflow:auto;float:left;position:relative;"> ' . implode('', $chunk) . '</div>';
 	}
 
 	$body .= '</div>';
 
-	createDoc($hostArrays, $subnet === '' ? 'all' : $subnet);
+	$name = $subnet;
 
-	$top = $config['base_path'] . '/plugins/gpsmap/XML/' . trim($subnet === '' ? 'all' : $subnet, '.') . '-top.html';
+	createDoc($hostArrays, $name);
 
-	gpsmap_write_file($top, $body);
+	gpsmap_write_file($config['base_path'] . '/plugins/gpsmap/XML/' . gpsmap_artifact_stem($name) . '-top.html', $body);
 }
diff --git a/includes/setup/database.php b/includes/setup/database.php
index 5dc1926..006eacf 100644
--- a/includes/setup/database.php
+++ b/includes/setup/database.php
@@ -19,52 +19,110 @@
  +-------------------------------------------------------------------------+
 */
 
-function gpsmap_upgrade_database() {
-	global $config, $database_default, $old;
+/* $old is the version being upgraded from.  It used to be read from a global
+ * that nothing ever set, which made every comparison below true and re-ran the
+ * whole migration history on every version change. */
+/* Backoff between attempts, so a failing migration cannot re-run an ALTER on
+ * Cacti's host table from every page view. */
+if (!defined('GPSMAP_UPGRADE_RETRY_SECONDS')) {
+	define('GPSMAP_UPGRADE_RETRY_SECONDS', 300);
+}
+
+function gpsmap_upgrade_database(string $old = ''): void {
+	global $config;
 
 	include_once($config['library_path'] . '/database.php');
 
-	gpsmap_setup_database();
+	$v = plugin_gpsmap_version();
 
-	if ($old < '1.6'){
-		db_execute('ALTER TABLE host CHANGE COLUMN latitude latitude DECIMAL(13,10) NOT NULL;');
-		db_execute('ALTER TABLE host ALTER COLUMN latitude SET DEFAULT `0.0000000000`;');
-		db_execute('ALTER TABLE host CHANGE COLUMN longitude longitude DECIMAL(13,10) NOT NULL;');
-		db_execute('ALTER TABLE host ALTER COLUMN longitude SET DEFAULT `0.0000000000`;');
+	$retry_after = (int) read_config_option('plugin_gpsmap_upgrade_retry_after', true);
+
+	if ($retry_after > time()) {
+		return;
 	}
 
-	if ($old < '2.1') {
+	/* gpsmap_setup_database() adds the host columns and creates the template
+	 * table, so its result belongs in the same gate as the migrations below. */
+	$ok = gpsmap_setup_database();
+
+	if (version_compare($old, '1.6', '<')) {
+		$ok = db_execute('ALTER TABLE host CHANGE COLUMN latitude latitude DECIMAL(13,10) NOT NULL DEFAULT 0.0000000000;') && $ok;
+		$ok = db_execute('ALTER TABLE host CHANGE COLUMN longitude longitude DECIMAL(13,10) NOT NULL DEFAULT 0.0000000000;') && $ok;
+	}
+
+	if (version_compare($old, '2.1', '<')) {
 		if (!db_index_exists('gpsmap_templates', 'templateID')) {
-			db_add_index('gpsmap_templates', 'unique', 'templateID', array('templateID'));
+			$ok = db_add_index('gpsmap_templates', 'unique', 'templateID', ['templateID']) && $ok;
 		}
 	}
 
 	include_once($config['base_path'] . '/plugins/gpsmap/setup.php');
+
+	/* Recorded last, and only when every migration reported success.
+	 * gpsmap_check_upgrade() gates on this option, so writing it earlier would
+	 * mark the plugin current even though a failed ALTER left the schema
+	 * behind, with no log line and no retry. */
+	if ($ok) {
+		/* Both records, together and only on success.  Plugin Management reads
+		 * plugin_config; gpsmap_check_upgrade() reads the settings option.
+		 * Writing either early reports the plugin current while the schema is
+		 * still behind. */
+		db_execute_prepared('UPDATE plugin_config SET version = ? WHERE directory = "gpsmap"', [$v['version']]);
+		set_config_option('plugin_gpsmap_version', $v['version']);
+		set_config_option('plugin_gpsmap_upgrade_retry_after', '0');
+
+		return;
+	}
+
+	/* Never record the version here: doing so would report a schema the upgrade
+	 * knows is incomplete as current, and nothing would re-arm the migration
+	 * when the transient cause clears.  Back off instead, so a lock timeout
+	 * cannot turn ordinary page views into sustained contention on host. */
+	set_config_option('plugin_gpsmap_upgrade_retry_after', (string) (time() + GPSMAP_UPGRADE_RETRY_SECONDS));
+
+	cacti_log('WARNING: gpsmap schema upgrade did not complete and will be retried after ' . GPSMAP_UPGRADE_RETRY_SECONDS . ' seconds.  If it keeps failing, run the ALTER TABLE statements in plugins/gpsmap/includes/setup/database.php by hand; the plugin will then record itself current on the next attempt.', false, 'GPSMAP');
 }
 
-function gpsmap_setup_database() {
+function gpsmap_setup_database(): bool {
 	$v = plugin_gpsmap_version();
 
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'latitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'longitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'GPScoverage', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'start', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'stop', 'type' => 'int(3)', 'NULL' => false, 'default' => '360', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'groupnum', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'rdistance', 'type' => 'decimal(10,6)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-
-	$data = array();
-	$data['columns'][] = array('name' => 'templateID', 'type' => 'int(11)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'templateName', 'type' => 'varchar(100)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'upimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'recoverimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'downimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'AP', 'type' => 'int(1)', 'NULL' => true);
-	$data['type'] = 'MyISAM';
-	$data['unique_keys'][] = array('name' => 'templateID' , 'columns' => 'templateID', 'unique' => true);
-	$data['comment'] = 'Map icon template';
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'latitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'longitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'GPScoverage', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'start', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'stop', 'type' => 'int(3)', 'NULL' => false, 'default' => '360', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'groupnum', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'rdistance', 'type' => 'decimal(10,6)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+
+	$data                  = [];
+	$data['columns'][]     = ['name' => 'templateID', 'type' => 'int(11)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'templateName', 'type' => 'varchar(100)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'upimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'recoverimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'downimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'AP', 'type' => 'int(1)', 'NULL' => true];
+	$data['type']          = 'InnoDB';
+	$data['unique_keys'][] = ['name' => 'templateID', 'columns' => 'templateID', 'unique' => true];
+	$data['comment']       = 'Map icon template';
 	api_plugin_db_table_create('gpsmap', 'gpsmap_templates', $data);
 
-	db_execute_prepared('UPDATE plugin_config SET version = ? WHERE directory = "gpsmap"', array($v['version']));
-}
+	$data                  = [];
+	$data['columns'][]     = ['name' => 'hostname', 'type' => 'varchar(255)', 'NULL' => false, 'default' => ''];
+	$data['columns'][]     = ['name' => 'address', 'type' => 'varchar(45)', 'NULL' => false, 'default' => ''];
+	$data['columns'][]     = ['name' => 'refreshed_at', 'type' => 'timestamp', 'NULL' => false, 'default' => 'CURRENT_TIMESTAMP'];
+	$data['primary']       = 'hostname';
+	$data['keys'][]        = ['name' => 'refreshed_at', 'columns' => 'refreshed_at'];
+	$data['type']          = 'InnoDB';
+	$data['comment']       = 'Asynchronously refreshed gpsmap hostname addresses';
+	api_plugin_db_table_create('gpsmap', 'plugin_gpsmap_dns_cache', $data);
 
+	/* The Cacti helpers do not report failure consistently, so confirm the
+	 * schema directly rather than trusting their return values. */
+	foreach (['latitude', 'longitude', 'GPScoverage', 'start', 'stop', 'groupnum', 'rdistance'] as $column) {
+		if (!db_column_exists('host', $column)) {
+			return false;
+		}
+	}
+
+	return db_table_exists('gpsmap_templates') && db_table_exists('plugin_gpsmap_dns_cache');
+}
diff --git a/includes/towerSelect.php b/includes/towerSelect.php
deleted file mode 100644
index e42082c..0000000
--- a/includes/towerSelect.php
+++ /dev/null
@@ -1,47 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2009-2013 Andrew Aloia                                    |
- | Copyright (C) 2014 Wixiweb                                              |
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- |                                                                         |
- | This program is free software; you can redistribute it and/or           |
- | modify it under the terms of the GNU General Public License             |
- | as published by the Free Software Foundation; either version 2          |
- | of the License, or (at your option) any later version.                  |
- |                                                                         |
- | This program is distributed in the hope that it will be useful,         |
- | but WITHOUT ANY WARRANTY; without even the implied warranty of          |
- | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           |
- | GNU General Public License for more details.                            |
- +-------------------------------------------------------------------------+
- | http://www.cacti.net/                                                   |
- +-------------------------------------------------------------------------+
-*/
-
-chdir('../../../');
-require_once('./include/auth.php');
-
-if (!isset($_SESSION['sess_user_id'])) {
-	exit;
-}
-
-if (function_exists('api_user_realm_auth') && !api_user_realm_auth('gpsmap.php')) {
-	exit;
-}
-
-$results = db_fetch_assoc_prepared("SELECT name, id FROM host_template", array());
-
-$body = '<ul>';
-
-if (cacti_sizeof($results)) {
-	foreach ($results as $row) {
-		$body .= '<li>' . html_escape($row['name']) . ' (ID: ' . html_escape($row['id']) . ')</li>';
-	}
-}
-
-$body .= '</ul>';
-
-print('<html>');
-print($body);
-print('</html>');
diff --git a/print.php b/print.php
index 7f4c628..79a53b8 100644
--- a/print.php
+++ b/print.php
@@ -20,9 +20,9 @@
 */
 
 chdir('../../');
+/* auth.php halts execution (exit/redirect) for unauthenticated users, so the
+ * markup below is only reached after successful authentication. */
 require_once('./include/auth.php');
-
-
 ?>
 <script language='javascript'>
 var mapEl = window.opener.document.getElementById('map');
diff --git a/setup.php b/setup.php
index ba181bd..2f6b682 100644
--- a/setup.php
+++ b/setup.php
@@ -76,7 +76,7 @@ function gpsmap_check_upgrade() {
 	$old = read_config_option('plugin_gpsmap_version', TRUE);
 	if ($current != $old) {
 		include_once($config['base_path'] . '/plugins/gpsmap/includes/setup/database.php');
-		gpsmap_upgrade_database();
+		gpsmap_upgrade_database((string) $old);
 	}
 
 	/* Migrate the misspelled 'gpsmap_latutude' key to 'gpsmap_latitude'.
diff --git a/tests/coverage.php b/tests/coverage.php
index 3229ae2..accac42 100644
--- a/tests/coverage.php
+++ b/tests/coverage.php
@@ -28,12 +28,15 @@
 }
 
 /* Files that hold logic.  The web entry points (gpsmap.php, gpstemplates.php,
- * print.php, includes/towerSelect.php) chdir() to the Cacti root and include
+ * print.php) chdir() to the Cacti root and include
  * include/auth.php, so they cannot execute outside a real installation and are
  * deliberately out of scope here. */
-$targets = array(
+$targets = [
 	'class/hosts_class.php',
 	'gpsmap_security.php',
+	'includes/dns.php',
+	'includes/setup/database.php',
+	'includes/polling.php',
 	'includes/polling/functions.php',
 	'includes/polling/processregion.php',
 	'includes/polling/coveragexml.php',
@@ -41,7 +44,7 @@
 	'includes/polling/iconskml.php',
 	'includes/icons.php',
 	'includes/customicons.php',
-);
+];
 
 /* run.php ends in exit(), so the report runs from a shutdown
  * handler and preserves the suite's own exit status when it fails. */
@@ -54,16 +57,16 @@
 require __DIR__ . '/run.php';
 
 function gpsmap_coverage_report(array $targets): void {
-		$status = 0;
+	$status = 0;
 
-		$coverage = xdebug_get_code_coverage();
-		xdebug_stop_code_coverage();
+	$coverage = xdebug_get_code_coverage();
+	xdebug_stop_code_coverage();
 
 	$root       = dirname(__DIR__);
 	$totalLines = 0;
-	$missing    = array();
+	$missing    = [];
 	$hitLines   = 0;
-	$rows       = array();
+	$rows       = [];
 
 	foreach ($targets as $rel) {
 		$abs = $root . '/' . $rel;
@@ -72,7 +75,7 @@ function gpsmap_coverage_report(array $targets): void {
 			/* A target that never executed would otherwise score 0/0 and drop
 			 * out of the total, letting the gate pass on a file the suite
 			 * never loaded. */
-			$rows[]    = array($rel, 0, 0, 0.0);
+			$rows[]    = [$rel, 0, 0, 0.0];
 			$missing[] = $rel;
 
 			continue;
@@ -82,7 +85,7 @@ function gpsmap_coverage_report(array $targets): void {
 		$hit        = 0;
 
 		foreach ($coverage[$abs] as $state) {
-			/* 1 = executed, -1 = executable but not executed, -2 = dead code. */
+			// 1 = executed, -1 = executable but not executed, -2 = dead code.
 			if ($state === -2) {
 				continue;
 			}
@@ -96,33 +99,33 @@ function gpsmap_coverage_report(array $targets): void {
 
 		$totalLines += $executable;
 		$hitLines   += $hit;
-		$rows[]      = array($rel, $hit, $executable, $executable ? $hit / $executable * 100 : 0.0);
-}
+		$rows[]      = [$rel, $hit, $executable, $executable ? $hit / $executable * 100 : 0.0];
+	}
 
-	echo "\nLine coverage\n";
-	echo str_repeat('-', 62) . "\n";
+	print "\nLine coverage\n";
+	print str_repeat('-', 62) . "\n";
 
 	foreach ($rows as $r) {
 		printf("%-42s %4d/%-4d %6.1f%%\n", $r[0], $r[1], $r[2], $r[3]);
-}
+	}
 
-	echo str_repeat('-', 62) . "\n";
+	print str_repeat('-', 62) . "\n";
 	$pct = $totalLines ? $hitLines / $totalLines * 100 : 0.0;
 	printf("%-42s %4d/%-4d %6.1f%%\n\n", 'TOTAL', $hitLines, $totalLines, $pct);
 
-		if ($missing !== array()) {
-			printf("FAIL: never executed, so not counted: %s\n", implode(', ', $missing));
-			exit(1);
-		}
+	if ($missing !== []) {
+		printf("FAIL: never executed, so not counted: %s\n", implode(', ', $missing));
+		exit(1);
+	}
 
-		$threshold = (float) (getenv('GPSMAP_COVERAGE_MIN') ?: 100);
+	$threshold = (float) (getenv('GPSMAP_COVERAGE_MIN') ?: 100);
 
-		if ($pct + 0.001 < $threshold) {
-			printf("FAIL: coverage %.1f%% is below the %.1f%% threshold\n", $pct, $threshold);
-			$status = 1;
-		}
+	if ($pct + 0.001 < $threshold) {
+		printf("FAIL: coverage %.1f%% is below the %.1f%% threshold\n", $pct, $threshold);
+		$status = 1;
+	}
 
-		if ($status !== 0) {
-			exit($status);
-		}
+	if ($status !== 0) {
+		exit($status);
+	}
 }
diff --git a/tests/harness.php b/tests/harness.php
index 527203f..454b351 100644
--- a/tests/harness.php
+++ b/tests/harness.php
@@ -19,18 +19,19 @@
 $GLOBALS['gpsmap_test_pass'] = 0;
 $GLOBALS['gpsmap_test_fail'] = 0;
 
-/* Rows the db stubs hand back.  Tests overwrite these per case. */
-$GLOBALS['gpsmap_stub_rows']     = array();
-$GLOBALS['gpsmap_stub_settings'] = array('base_url' => 'https://cacti.example/');
+// Rows the db stubs hand back.  Tests overwrite these per case.
+$GLOBALS['gpsmap_stub_rows']     = [];
+$GLOBALS['gpsmap_stub_settings'] = ['base_url' => 'https://cacti.example/'];
+$GLOBALS['gpsmap_stub_plugins']  = [];
 
 function assert_equal($label, $expected, $actual) {
 	if ($expected === $actual) {
-		echo "PASS  $label\n";
+		print "PASS  $label\n";
 		$GLOBALS['gpsmap_test_pass']++;
 	} else {
-		echo "FAIL  $label\n";
-		echo '      expected: ' . var_export($expected, true) . "\n";
-		echo '      actual:   ' . var_export($actual, true) . "\n";
+		print "FAIL  $label\n";
+		print '      expected: ' . var_export($expected, true) . "\n";
+		print '      actual:   ' . var_export($actual, true) . "\n";
 		$GLOBALS['gpsmap_test_fail']++;
 	}
 }
@@ -52,33 +53,51 @@ function assert_not_contains($label, string $needle, string $haystack) {
 }
 
 function gpsmap_test_summary(): int {
-	echo "\n";
-	echo 'Results: ' . $GLOBALS['gpsmap_test_pass'] . ' passed, ' . $GLOBALS['gpsmap_test_fail'] . " failed\n";
+	print "\n";
+	print 'Results: ' . $GLOBALS['gpsmap_test_pass'] . ' passed, ' . $GLOBALS['gpsmap_test_fail'] . " failed\n";
 
 	return $GLOBALS['gpsmap_test_fail'] > 0 ? 1 : 0;
 }
 
-/* ------------------------------------------------------------------ */
-/* Cacti stubs                                                         */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// Cacti stubs
+// ------------------------------------------------------------------
 
 if (!isset($GLOBALS['config'])) {
-	$GLOBALS['config'] = array(
+	$GLOBALS['config'] = [
 		'base_path' => dirname(__DIR__, 3) . '/cacti-stub',
 		'url_path'  => '/cacti/',
-	);
+	];
 }
 
 if (!function_exists('cacti_sizeof')) {
-	function cacti_sizeof($var) { return is_array($var) ? count($var) : 0; }
+	function cacti_sizeof($var) {
+		return is_array($var) ? count($var) : 0;
+	}
 }
 
 if (!function_exists('db_fetch_assoc')) {
-	function db_fetch_assoc($sql) { return gpsmap_stub_query($sql); }
+	function db_fetch_assoc($sql) {
+		return gpsmap_stub_query($sql);
+	}
 }
 
 if (!function_exists('db_fetch_assoc_prepared')) {
-	function db_fetch_assoc_prepared($sql, $params = array()) { return gpsmap_stub_query($sql); }
+	function db_fetch_assoc_prepared($sql, $params = []) {
+		return gpsmap_stub_query($sql);
+	}
+}
+
+if (!function_exists('db_table_exists')) {
+	function db_table_exists($table, $log = true, $db_conn = false) {
+		return !in_array($table, $GLOBALS['gpsmap_stub_missing_tables'] ?? [], true);
+	}
+}
+
+if (!function_exists('api_plugin_is_enabled')) {
+	function api_plugin_is_enabled($plugin) {
+		return in_array($plugin, $GLOBALS['gpsmap_stub_plugins'], true);
+	}
 }
 
 /* Route each query to a named fixture bucket so a test can set them
@@ -89,22 +108,26 @@ function gpsmap_stub_query($sql) {
 	if (str_contains($sql, 'FROM `host` AS h')) {
 		$GLOBALS['gpsmap_stub_host_sql'] = $sql;
 
-		return $GLOBALS['gpsmap_stub_rows']['hosts'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['hosts'] ?? [];
 	}
 
 	if (str_contains($sql, '`AP` = 1')) {
-		return $GLOBALS['gpsmap_stub_rows']['towers'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['towers'] ?? [];
 	}
 
 	if (str_contains($sql, '`host_template`')) {
-		return $GLOBALS['gpsmap_stub_rows']['templates'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['templates'] ?? [];
 	}
 
 	if (str_contains($sql, 'gpsmap_templates')) {
-		return $GLOBALS['gpsmap_stub_rows']['icons'] ?? array();
+		if (str_contains($sql, 'SELECT DISTINCT h.hostname')) {
+			return $GLOBALS['gpsmap_stub_rows']['dns'] ?? [];
+		}
+
+		return $GLOBALS['gpsmap_stub_rows']['icons'] ?? [];
 	}
 
-	return array();
+	return [];
 }
 
 if (!function_exists('read_config_option')) {
@@ -119,25 +142,39 @@ function cacti_log($message, $stdout = false, $env = '') {
 	}
 }
 
+if (!function_exists('exec_background')) {
+	function exec_background($command, $args) {
+		$GLOBALS['gpsmap_stub_background'][] = [$command, $args];
+	}
+}
+
 if (!function_exists('is_ipaddress')) {
-	function is_ipaddress($ip) { return filter_var($ip, FILTER_VALIDATE_IP) !== false; }
+	function is_ipaddress($ip) {
+		return filter_var($ip, FILTER_VALIDATE_IP) !== false;
+	}
 }
 
 if (!function_exists('html_escape')) {
-	function html_escape($text) { return htmlspecialchars((string) $text, ENT_QUOTES, 'UTF-8'); }
+	function html_escape($text) {
+		return htmlspecialchars((string) $text, ENT_QUOTES, 'UTF-8');
+	}
 }
 
 if (!function_exists('__')) {
 	function __($format, ...$args) {
-		/* Cacti's last argument is the text domain when more than one is given. */
-		if (count($args) > 1) { array_pop($args); }
+		// Cacti's last argument is the text domain when more than one is given.
+		if (count($args) > 1) {
+			array_pop($args);
+		}
 
-		return $args === array() ? $format : vsprintf($format, $args);
+		return $args === [] ? $format : vsprintf($format, $args);
 	}
 }
 
 if (!function_exists('__esc')) {
-	function __esc($format, ...$args) { return html_escape(__($format, ...$args)); }
+	function __esc($format, ...$args) {
+		return html_escape(__($format, ...$args));
+	}
 }
 
 /* Scratch Cacti root.  class/ and includes/ are symlinked back to the real
@@ -157,7 +194,7 @@ function gpsmap_test_tmpdir(): string {
 	@mkdir($plugin . '/XML', 0700, true);
 	@mkdir($plugin . '/images/icons', 0700, true);
 
-	foreach (array('class', 'includes') as $link) {
+	foreach (['class', 'includes', 'INFO', 'setup.php', 'gpsmap_security.php'] as $link) {
 		if (!file_exists($plugin . '/' . $link)) {
 			@symlink($repo . '/' . $link, $plugin . '/' . $link);
 		}
@@ -181,18 +218,18 @@ function gpsmap_test_rmtree(string $path): void {
 		return;
 	}
 
-	foreach (array_diff(scandir($path), array('.', '..')) as $entry) {
+	foreach (array_diff(scandir($path), ['.', '..']) as $entry) {
 		gpsmap_test_rmtree($path . '/' . $entry);
 	}
 
 	@rmdir($path);
 }
 
-/* Replaces the icon fixture folder with exactly the given file names. */
+// Replaces the icon fixture folder with exactly the given file names.
 function gpsmap_test_icons(array $names): string {
 	$dir = gpsmap_test_tmpdir() . '/plugins/gpsmap/images/icons';
 
-	foreach (array_diff(scandir($dir), array('.', '..')) as $entry) {
+	foreach (array_diff(scandir($dir), ['.', '..']) as $entry) {
 		@unlink($dir . '/' . $entry);
 	}
 
@@ -203,7 +240,7 @@ function gpsmap_test_icons(array $names): string {
 	return $dir;
 }
 
-/* Points $config at the scratch root for the duration of a test file. */
+// Points $config at the scratch root for the duration of a test file.
 function gpsmap_test_use_tmp_root(): void {
 	$GLOBALS['config']['base_path'] = gpsmap_test_tmpdir();
 }
@@ -213,15 +250,33 @@ function gpsmap_test_use_tmp_root(): void {
 class GpsmapShortWriteStream {
 	public $context;
 
-	public function stream_open($path, $mode, $options, &$opened_path) { return true; }
-	public function stream_write($data) { return max(0, strlen($data) - 1); }
-	public function stream_close() { return true; }
-	public function stream_flush() { return true; }
-	public function stream_eof() { return true; }
-	public function stream_stat() { return array(); }
-	public function url_stat($path, $flags) { return array(); }
-	public function unlink($path) { return true; }
-	public function rename($from, $to) { return false; }
+	public function stream_open($path, $mode, $options, &$opened_path) {
+		return true;
+	}
+	public function stream_write($data) {
+		return max(0, strlen($data) - 1);
+	}
+	public function stream_close() {
+		return true;
+	}
+	public function stream_flush() {
+		return true;
+	}
+	public function stream_eof() {
+		return true;
+	}
+	public function stream_stat() {
+		return [];
+	}
+	public function url_stat($path, $flags) {
+		return [];
+	}
+	public function unlink($path) {
+		return true;
+	}
+	public function rename($from, $to) {
+		return false;
+	}
 }
 
 if (!in_array('gpsmapshort', stream_get_wrappers(), true)) {
diff --git a/tests/run.php b/tests/run.php
index 36a55f9..9024945 100644
--- a/tests/run.php
+++ b/tests/run.php
@@ -20,7 +20,7 @@
 
 require_once __DIR__ . '/harness.php';
 
-foreach (array('test_functions.php', 'test_host.php', 'test_security.php', 'test_icons.php', 'test_poller_isolation.php', 'test_polling.php') as $file) {
+foreach (array('test_functions.php', 'test_host.php', 'test_security.php', 'test_icons.php', 'test_poller_isolation.php', 'test_upgrade.php', 'test_polling.php') as $file) {
 	echo "\n--- $file ---\n";
 
 	require __DIR__ . '/' . $file;
diff --git a/tests/test_functions.php b/tests/test_functions.php
index 01bd653..c60e660 100644
--- a/tests/test_functions.php
+++ b/tests/test_functions.php
@@ -25,16 +25,16 @@
 require_once __DIR__ . '/harness.php';
 require_once __DIR__ . '/../includes/polling/functions.php';
 
-/* ------------------------------------------------------------------ */
-/* parseToXML — encoding correctness                                   */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// parseToXML — encoding correctness
+// ------------------------------------------------------------------
 
-/* Basic entity encoding. */
+// Basic entity encoding.
 assert_equal('parseToXML: ampersand',      '&amp;',       parseToXML('&'));
 assert_equal('parseToXML: less-than',      '&lt;',        parseToXML('<'));
 assert_equal('parseToXML: greater-than',   '&gt;',        parseToXML('>'));
 assert_equal('parseToXML: double-quote',   '&quot;',      parseToXML('"'));
-/* ENT_XML1 uses &apos; for single quotes (XML 1.0 named entity, not &#039;). */
+// ENT_XML1 uses &apos; for single quotes (XML 1.0 named entity, not &#039;).
 assert_equal('parseToXML: single-quote',   '&apos;',      parseToXML("'"));
 
 /* The old implementation double-encoded: '<br>' became '&amp;lt;br&amp;gt;'
@@ -46,26 +46,26 @@
 	parseToXML('<br>')
 );
 
-/* An already-encoded string must not be double-encoded. */
+// An already-encoded string must not be double-encoded.
 assert_equal(
 	'parseToXML: no double-encoding of existing entity',
 	'&amp;amp;',
 	parseToXML('&amp;')
 );
 
-/* Plain strings pass through unchanged. */
+// Plain strings pass through unchanged.
 assert_equal('parseToXML: plain string',   'hello world', parseToXML('hello world'));
 assert_equal('parseToXML: numeric string', '42',          parseToXML(42));
 assert_equal('parseToXML: empty string',   '',            parseToXML(''));
 
-/* ------------------------------------------------------------------ */
-/* calcKm — distance calculation and backward-compat alias            */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — distance calculation and backward-compat alias
+// ------------------------------------------------------------------
 
-/* Same point — distance must be 0. */
+// Same point — distance must be 0.
 assert_equal('calcKm: same point is 0', 0.0, calcKm(0, 0, 0, 0));
 
-/* Known approximate: London (51.5, -0.1) to Paris (48.8, 2.3) ~ 341 km. */
+// Known approximate: London (51.5, -0.1) to Paris (48.8, 2.3) ~ 341 km.
 $dist = calcKm(51.5, -0.1, 48.8, 2.3);
 assert_true('calcKm: London-Paris between 330 and 360 km', $dist >= 330 && $dist <= 360);
 
@@ -77,22 +77,19 @@
 	calcMeters(51.5, -0.1, 48.8, 2.3)
 );
 
-/* ------------------------------------------------------------------ */
-/* Subnet parameter validation regex (mirrors gpsmap.php logic)       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// Subnet parameter validation regex (mirrors gpsmap.php logic)
+// ------------------------------------------------------------------
 
-$valid_re   = '/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$/';
+$valid_re   = '/^(?:all|[0-9]+(?:\.[0-9]+){0,2}|v6-(?:16-[0-9a-f]{4}|32-[0-9a-f]{8}|48-[0-9a-f]{12}))$/';
 
-/* Valid values. */
+// Valid values.
 assert_true('subnet regex: "all"',              preg_match($valid_re, 'all'));
-assert_true('subnet regex: IP octets with -',   preg_match($valid_re, '192-168-1'));
-assert_true('subnet regex: alphanumeric',       preg_match($valid_re, 'region1'));
-assert_true('subnet regex: underscore',         preg_match($valid_re, 'region_1'));
-assert_true('subnet regex: uppercase',          preg_match($valid_re, 'RegionA'));
+assert_true('subnet regex: IPv6 token',          preg_match($valid_re, 'v6-32-20010db8'));
 assert_true('subnet regex: dotted subnet',      preg_match($valid_re, '10.0.0'));
-assert_true('subnet regex: dotted with dash',   preg_match($valid_re, '192-168-1.0'));
+assert_false('subnet regex: arbitrary region',  preg_match($valid_re, 'region1'));
 
-/* Values that must be rejected (path traversal and other dangerous input). */
+// Values that must be rejected (path traversal and other dangerous input).
 assert_false('subnet regex: ".."',              preg_match($valid_re, '..'));
 assert_false('subnet regex: "."',               preg_match($valid_re, '.'));
 assert_false('subnet regex: "../etc/passwd"',   preg_match($valid_re, '../etc/passwd'));
@@ -104,16 +101,16 @@
 assert_false('subnet regex: percent-encoded',   preg_match($valid_re, '..%2fetc'));
 assert_false('subnet regex: space',             preg_match($valid_re, 'a b'));
 
-/* ------------------------------------------------------------------ */
-/* parseToXML — multibyte UTF-8                                        */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// parseToXML — multibyte UTF-8
+// ------------------------------------------------------------------
 
 assert_equal('parseToXML: multibyte CJK', '日本語', parseToXML('日本語'));
 assert_equal('parseToXML: multibyte with entities', '&lt;日本語&gt;', parseToXML('<日本語>'));
 
-/* ------------------------------------------------------------------ */
-/* calcKm — negative coordinates (southern/western hemispheres)        */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — negative coordinates (southern/western hemispheres)
+// ------------------------------------------------------------------
 
 /* Southern hemisphere: Cape Town (-33.9, 18.4) to Buenos Aires (-34.6, -58.4).
  * The flat-earth approximation in calcKm overestimates at large longitude
@@ -122,9 +119,9 @@
 assert_true('calcKm: negative coords (CapeTown-BuenosAires) > 0', $dist_neg > 0);
 assert_true('calcKm: negative coords is finite and positive', is_finite($dist_neg) && $dist_neg > 0);
 
-/* ------------------------------------------------------------------ */
-/* calcKm — symmetry: distance(A,B) === distance(B,A)                 */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — symmetry: distance(A,B) === distance(B,A)
+// ------------------------------------------------------------------
 
 assert_equal(
 	'calcKm: symmetry London-Paris',
@@ -138,18 +135,18 @@
 	calcKm(-34.6, -58.4, -33.9, 18.4)
 );
 
-/* ------------------------------------------------------------------ */
-/* calcKm — antipodal points (max distance ~20,000 km)                */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — antipodal points (max distance ~20,000 km)
+// ------------------------------------------------------------------
 
 $dist_anti = calcKm(0, 0, 0, 180);
 assert_true('calcKm: antipodal not NaN', !is_nan($dist_anti));
 assert_true('calcKm: antipodal > 0', $dist_anti > 0);
 assert_true('calcKm: antipodal <= 21000 km', $dist_anti <= 21000);
 
-/* ------------------------------------------------------------------ */
-/* coordCheck — validation                                             */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// coordCheck — validation
+// ------------------------------------------------------------------
 
 assert_equal('coordCheck: valid positive',    '45.123',  coordCheck('45.123'));
 assert_equal('coordCheck: valid negative',    '-90.000', coordCheck('-90.000'));
@@ -159,7 +156,7 @@
 assert_equal('coordCheck: valid zero',        '0.000',   coordCheck('0.000'));
 assert_equal('coordCheck: negative longitude', '-122.4194', coordCheck('-122.4194'));
 
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
 if (!defined('GPSMAP_TEST_SUITE')) {
 	exit(gpsmap_test_summary());
 }
diff --git a/tests/test_icons.php b/tests/test_icons.php
index 31d97ae..e7e9e5b 100644
--- a/tests/test_icons.php
+++ b/tests/test_icons.php
@@ -18,13 +18,14 @@
 
 require_once __DIR__ . '/harness.php';
 require_once __DIR__ . '/../setup.php';
+require_once __DIR__ . '/../gpsmap_security.php';
 require_once __DIR__ . '/../includes/polling/iconskml.php';
 
 gpsmap_test_use_tmp_root();
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_icon_identifier                                              */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_icon_identifier
+// ------------------------------------------------------------------
 
 assert_equal('identifier: simple name',      'Green',   gpsmap_icon_identifier('Green.png'));
 assert_equal('identifier: underscore start', '_x',      gpsmap_icon_identifier('_x.png'));
@@ -37,11 +38,11 @@
 assert_equal('identifier: quote injection',  null,      gpsmap_icon_identifier("x';alert(1);//.png"));
 assert_equal('identifier: space',            null,      gpsmap_icon_identifier('two words.png'));
 
-/* ------------------------------------------------------------------ */
-/* includes/icons.php - JavaScript emitted into an inline <script>      */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// includes/icons.php - JavaScript emitted into an inline <script>
+// ------------------------------------------------------------------
 
-gpsmap_test_icons(array('Green.png', 'GoogleBlue.PNG', 'ap.v2.png', 'my-icon.png', 'notes.txt', 'noext'));
+gpsmap_test_icons(['Green.png', 'GoogleBlue.PNG', 'ap.v2.png', 'my-icon.png', 'notes.txt', 'noext']);
 
 $cwd = getcwd();
 chdir(gpsmap_test_tmpdir());
@@ -58,13 +59,14 @@
 assert_not_contains('icons.php: ignores extensionless', 'gpsmap.noext',         $js);
 assert_contains('icons.php: url is json encoded',      '"/cacti/plugins/gpsmap/images/icons/Green.png"', $js);
 
-/* Every emitted assignment target must be a bare identifier. */
+// Every emitted assignment target must be a bare identifier.
 preg_match_all('/gpsmap\.([^ ]+) = \{/', $js, $m);
+
 foreach ($m[1] as $name) {
 	assert_true('icons.php: identifier is bare - ' . $name, (bool) preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $name));
 }
 
-/* An unreadable icon directory must not emit anything. */
+// An unreadable icon directory must not emit anything.
 $cwd = getcwd();
 chdir(sys_get_temp_dir());
 ob_start();
@@ -73,11 +75,11 @@
 chdir($cwd);
 assert_not_contains('icons.php: missing directory emits no icons', 'gpsmap.', $empty);
 
-/* ------------------------------------------------------------------ */
-/* iconskml() - KML Style ids                                          */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// iconskml() - KML Style ids
+// ------------------------------------------------------------------
 
-gpsmap_test_icons(array('Green.png', 'Red.jpg', 'Amber.jpeg', 'Node.gif', 'ap.v2.png', 'notes.txt'));
+gpsmap_test_icons(['Green.png', 'Red.jpg', 'Amber.jpeg', 'Node.gif', 'ap.v2.png', 'notes.txt']);
 
 $kml = iconskml();
 
@@ -89,34 +91,76 @@
 assert_not_contains('iconskml: ignores non-images', 'notes',       $kml);
 assert_contains('iconskml: absolute href',  'https://cacti.example//cacti/plugins/gpsmap/images/icons/Green.png', $kml);
 
-/* Missing directory is logged, not fatal. */
-$GLOBALS['gpsmap_stub_log']      = array();
+// Missing directory is logged, not fatal.
+$GLOBALS['gpsmap_stub_log']      = [];
 $saved                           = $GLOBALS['config']['base_path'];
 $GLOBALS['config']['base_path']  = sys_get_temp_dir() . '/gpsmap-no-such-root';
 assert_equal('iconskml: missing directory returns empty', '', @iconskml());
 assert_true('iconskml: logs the missing directory', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'could not open icon directory'));
 $GLOBALS['config']['base_path'] = $saved;
 
-/* ------------------------------------------------------------------ */
-/* customicons.php - property-access position, degrades to undefined   */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// customicons.php - property-access position, degrades to undefined
+// ------------------------------------------------------------------
 
-$GLOBALS['gpsmap_stub_rows']['icons'] = array(
-	array('templateID' => '10', 'upimage' => 'Green.png', 'downimage' => 'Red.png',    'recoverimage' => 'Yellow.png'),
-	array('templateID' => '11', 'upimage' => 'ap.v2.png', 'downimage' => 'my-icon.png', 'recoverimage' => ''),
-);
+$GLOBALS['gpsmap_stub_rows']['icons'] = [
+	['templateID' => '10', 'upimage' => 'Green.png', 'downimage' => 'Red.png',    'recoverimage' => 'Yellow.png'],
+	['templateID' => '11', 'upimage' => 'ap.v2.png', 'downimage' => 'my-icon.png', 'recoverimage' => ''],
+];
 
 ob_start();
 include __DIR__ . '/../includes/customicons.php';
 $custom = ob_get_clean();
 
 assert_contains('customicons: maps a good icon',   '["10up"] = gpsmap.Green;',    $custom);
+assert_contains('customicons: alert uses down icon', '["10alert"] = gpsmap.Red;', $custom);
 assert_contains('customicons: unsafe degrades',    '["11up"] = gpsmap.undefined;', $custom);
 assert_contains('customicons: keeps builtin ups',  "gpsmap.customIcons['up'] = gpsmap.Green;", $custom);
 assert_contains('customicons: keeps disabled',     "gpsmap.customIcons['disabled'] = gpsmap.Black;", $custom);
 assert_equal('gpsmap_safe_icon_base: good name',   'Green',     gpsmap_safe_icon_base('Green.png'));
 assert_equal('gpsmap_safe_icon_base: bad name',    'undefined', gpsmap_safe_icon_base('ap.v2.png'));
 
+// ------------------------------------------------------------------
+// getIcons() must offer exactly what the renderers can draw
+// ------------------------------------------------------------------
+
+// getIcons() reads a path relative to the Cacti root.
+gpsmap_test_icons(['Green.png', 'Node2.gif', 'my-icon.png', 'ap.v2.png', 'notes.txt', 'noext']);
+
+$cwd = getcwd();
+chdir(gpsmap_test_tmpdir());
+$offered = getIcons();
+chdir($cwd);
+
+assert_true('getIcons: offers a renderable icon',      isset($offered['Green.png']));
+assert_true('getIcons: offers a digit-bearing name',   isset($offered['Node2.gif']));
+assert_false('getIcons: hides hyphenated name',        isset($offered['my-icon.png']));
+assert_false('getIcons: hides dotted name',            isset($offered['ap.v2.png']));
+assert_false('getIcons: hides non-images',             isset($offered['notes.txt']));
+assert_false('getIcons: hides extensionless files',    isset($offered['noext']));
+
+/* The dropdown and the JavaScript emitter must never disagree: anything
+ * offered here has to survive gpsmap_icon_identifier(). */
+foreach (array_keys($offered) as $name) {
+	assert_true('getIcons: offered name is renderable - ' . $name, gpsmap_icon_identifier($name) !== null);
+}
+
+/* The path comes from base_path, not the working directory, so poller and CLI
+ * callers see the same list as the web pages. */
+$savedRoot = $GLOBALS['config']['base_path'];
+$cwd       = getcwd();
+chdir(sys_get_temp_dir());
+assert_true('getIcons: resolves regardless of the working directory', isset(getIcons()['Green.png']));
+chdir($cwd);
+
+$GLOBALS['config']['base_path'] = sys_get_temp_dir() . '/gpsmap-no-such-root';
+assert_equal('getIcons: missing directory yields no icons', [], @getIcons());
+$GLOBALS['config']['base_path'] = $savedRoot;
+
+// Saving still falls back when a name is not on the list.
+assert_equal('save: hyphenated name rejected on save', 'Green.png', gpsmap_normalize_icon_name('my-icon.png', $offered));
+assert_equal('save: offered name accepted on save',    'Green.png', gpsmap_normalize_icon_name('Green.png', $offered));
+
 if (!defined('GPSMAP_TEST_SUITE')) {
 	exit(gpsmap_test_summary());
 }
diff --git a/tests/test_polling.php b/tests/test_polling.php
index c26a19c..f3147c0 100644
--- a/tests/test_polling.php
+++ b/tests/test_polling.php
@@ -20,12 +20,21 @@
 require_once __DIR__ . '/../class/hosts_class.php';
 require_once __DIR__ . '/../includes/polling/functions.php';
 require_once __DIR__ . '/../includes/polling/processregion.php';
+require_once __DIR__ . '/../includes/dns.php';
+
+if (!function_exists('db_execute_prepared')) {
+	function db_execute_prepared($sql, $params = [], $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_execute'][] = [$sql, $params];
+
+		return true;
+	}
+}
 
 gpsmap_test_use_tmp_root();
-gpsmap_test_icons(array('Green.png', 'Red.png', 'Yellow.png', 'GoogleBlue.png', 'ap.v2.png', 'readme.txt'));
+gpsmap_test_icons(['Green.png', 'Red.png', 'Yellow.png', 'GoogleBlue.png', 'ap.v2.png', 'readme.txt']);
 
-function gpsmap_test_row(array $over = array()): array {
-	return $over + array(
+function gpsmap_test_row(array $over = []): array {
+	return $over + [
 		'id'               => '1',
 		'host_template_id' => '10',
 		'hostname'         => '10.1.2.3',
@@ -45,12 +54,14 @@ function gpsmap_test_row(array $over = array()): array {
 		'upimage'          => 'Green.png',
 		'downimage'        => 'Red.png',
 		'recoverimage'     => 'Yellow.png',
-	);
+		'cached_address'   => null,
+		'thold_alarm'      => '0',
+	];
 }
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_xml_path / gpsmap_write_file                                 */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_xml_path / gpsmap_write_file
+// ------------------------------------------------------------------
 
 $root = gpsmap_test_tmpdir();
 
@@ -68,31 +79,31 @@ function gpsmap_test_row(array $over = array()): array {
 assert_true('gpsmap_write_file: writes', gpsmap_write_file(gpsmap_xml_path('probe', 'xml'), 'body'));
 assert_equal('gpsmap_write_file: contents', 'body', file_get_contents(gpsmap_xml_path('probe', 'xml')));
 
-$GLOBALS['gpsmap_stub_log'] = array();
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('gpsmap_write_file: unwritable path returns false', gpsmap_write_file($root . '/no/such/dir/x.xml', 'body'));
 assert_true('gpsmap_write_file: logs the failure', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
 
-/* ------------------------------------------------------------------ */
-/* getTowerIds / createTypeArray                                       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// getTowerIds / createTypeArray
+// ------------------------------------------------------------------
 
-$GLOBALS['gpsmap_stub_rows']['towers'] = array();
-assert_equal('getTowerIds: sentinel when no towers', array(9999), getTowerIds());
+$GLOBALS['gpsmap_stub_rows']['towers'] = [];
+assert_equal('getTowerIds: sentinel when no towers', [9999], getTowerIds());
 
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'), array('templateID' => '11'));
-assert_equal('getTowerIds: template ids', array('10', '11'), getTowerIds());
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10'], ['templateID' => '11']];
+assert_equal('getTowerIds: template ids', ['10', '11'], getTowerIds());
 
-$GLOBALS['gpsmap_stub_rows']['templates'] = array(
-	array('id' => '10', 'name' => 'Tower'),
-	array('id' => '20', 'name' => 'Switch'),
-);
-assert_equal('createTypeArray: id keyed names', array('10' => 'Tower', '20' => 'Switch'), createTypeArray());
+$GLOBALS['gpsmap_stub_rows']['templates'] = [
+	['id' => '10', 'name' => 'Tower'],
+	['id' => '20', 'name' => 'Switch'],
+];
+assert_equal('createTypeArray: id keyed names', ['10' => 'Tower', '20' => 'Switch'], createTypeArray());
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_marker                                                       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_marker
+// ------------------------------------------------------------------
 
-$typeArray = array('10' => 'Tower');
+$typeArray = ['10' => 'Tower'];
 $marker    = gpsmap_marker(gpsmap_test_marker_host(), $typeArray, '0', false);
 
 assert_contains('gpsmap_marker: id',        'id="5"',            $marker);
@@ -114,38 +125,38 @@ function gpsmap_test_marker_host(string $type = '10'): host {
 		0, '99', 'up', '1', 'on', 'Green.png', 'Red.png', 'Yellow.png', '0', '360', '1');
 }
 
-/* createXMLNodes skips anything the traversal switched off. */
-$visible = gpsmap_test_marker_host();
-$hidden  = gpsmap_test_marker_host();
+// createXMLNodes skips anything the traversal switched off.
+$visible         = gpsmap_test_marker_host();
+$hidden          = gpsmap_test_marker_host();
 $hidden->showMap = 0;
 
-$nodes = createXMLNodes(array($visible, $hidden));
+$nodes = createXMLNodes([$visible, $hidden]);
 assert_equal('createXMLNodes: hidden hosts are skipped', 1, substr_count($nodes, '<marker '));
-assert_equal('createXMLNodes: empty input', '', createXMLNodes(array()));
-
-/* ------------------------------------------------------------------ */
-/* region(): full poller pass                                          */
-/* ------------------------------------------------------------------ */
-
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10', 'groupnum' => '1')),
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.1.2.4', 'host_template_id' => '20', 'groupnum' => '1', 'status' => '1',
-		/* same group as the tower but 250km away, so the coverage radius has to grow */
-		'latitude' => '53.4808', 'longitude' => '-2.2426')),
-	gpsmap_test_row(array('id' => '3', 'hostname' => '10.9.9.9', 'host_template_id' => '20', 'groupnum' => '2', 'status' => '2')),
-	/* filtered: no coordinates */
-	gpsmap_test_row(array('id' => '4', 'latitude' => '0.000', 'longitude' => '0.000')),
-	gpsmap_test_row(array('id' => '5', 'longitude' => '0.000')),
-	/* filtered: name does not resolve to a dotted quad */
-	gpsmap_test_row(array('id' => '6', 'hostname' => 'not-an-ip')),
-	/* disabled device keeps its own status label */
-	gpsmap_test_row(array('id' => '7', 'hostname' => '10.1.2.7', 'disabled' => 'on', 'status' => '3')),
-	/* status outside 1/2/3 falls through to 'undefined' */
-	gpsmap_test_row(array('id' => '8', 'hostname' => '10.1.2.8', 'status' => '9')),
-	/* GoogleXxx icons map onto Google's own KML styles */
-	gpsmap_test_row(array('id' => '9', 'hostname' => '10.1.2.9', 'upimage' => 'GoogleBlue.png')),
-);
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
+assert_equal('createXMLNodes: empty input', '', createXMLNodes([]));
+
+// ------------------------------------------------------------------
+// region(): full poller pass
+// ------------------------------------------------------------------
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10', 'groupnum' => '1']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.1.2.4', 'host_template_id' => '20', 'groupnum' => '1', 'status' => '1',
+		// same group as the tower but 250km away, so the coverage radius has to grow
+		'latitude' => '53.4808', 'longitude' => '-2.2426']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '10.9.9.9', 'host_template_id' => '20', 'groupnum' => '2', 'status' => '2']),
+	// filtered: no coordinates
+	gpsmap_test_row(['id' => '4', 'latitude' => '0.000', 'longitude' => '0.000']),
+	gpsmap_test_row(['id' => '5', 'longitude' => '0.000']),
+	// filtered: name does not resolve to a dotted quad
+	gpsmap_test_row(['id' => '6', 'hostname' => 'not-an-ip']),
+	// disabled device keeps its own status label
+	gpsmap_test_row(['id' => '7', 'hostname' => '10.1.2.7', 'disabled' => 'on', 'status' => '3']),
+	// status outside 1/2/3 falls through to 'undefined'
+	gpsmap_test_row(['id' => '8', 'hostname' => '10.1.2.8', 'status' => '9']),
+	// GoogleXxx icons map onto Google's own KML styles
+	gpsmap_test_row(['id' => '9', 'hostname' => '10.1.2.9', 'upimage' => 'GoogleBlue.png']),
+];
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
 
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('all');
@@ -169,29 +180,29 @@ function gpsmap_test_marker_host(string $type = '10'): host {
 assert_contains('region: top html nav',          'gpstopmenu',  $top);
 assert_contains('region: top html subnet link',  'subnet=10',   $top);
 
-/* Tower markers carry the coverage radius grown to the furthest group member. */
+// Tower markers carry the coverage radius grown to the furthest group member.
 assert_true('region: coverage radius grows beyond zero', (bool) preg_match('/radius="[1-9][0-9]*(\.[0-9]+)?"/', $xml));
 
-/* enableAll off takes the WHERE-clause branch. */
+// enableAll off takes the WHERE-clause branch.
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = '';
 region('10.1.2.');
 $deep = file_get_contents(gpsmap_xml_path('10.1.2.', 'xml'));
 assert_contains('region: subnet pass writes its own file', '<markers>', $deep);
 
-/* Deepest level emits per-device graph links. */
+// Deepest level emits per-device graph links.
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('10.1.2.');
 assert_contains('region: preempt 3 links to graphs', 'graph_view.php', file_get_contents($root . '/plugins/gpsmap/XML/10.1.2-top.html'));
 
-/* Beyond the deepest level every host is switched off. */
+// Beyond the deepest level every host is switched off.
 region('10.1.2.3.4.');
 assert_not_contains('region: past deepest level draws no markers', '<marker ', file_get_contents(gpsmap_xml_path('10.1.2.3.4.', 'xml')));
 
-/* Empty subnet is treated as 'all'. */
+// Empty subnet is treated as 'all'.
 region('');
 assert_true('region: empty subnet writes the all- files', file_exists($root . '/plugins/gpsmap/XML/all-top.html'));
 
-/* callRegion wires the includes together. */
+// callRegion wires the includes together.
 callRegion('all');
 assert_contains('callRegion: writes the navigation file', 'gpstopmenu', file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
 
@@ -220,66 +231,269 @@ function gpsmap_test_tower_radius(string $xml): ?float {
 
 /* Coverage radius: only devices sharing the tower's group widen it, and it
  * lands on the furthest member rather than the last one seen. */
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
-$GLOBALS['gpsmap_stub_rows']['hosts']  = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	/* different group, must not widen the tower */
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '7',
-		'latitude' => '-33.8688', 'longitude' => '151.2093')),
-);
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	// different group, must not widen the tower
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '7',
+		'latitude'           => '-33.8688', 'longitude' => '151.2093']),
+];
 region('all');
 assert_equal('coverageXML: other groups do not widen the radius', 0.0, gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))));
 
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	/* furthest member listed first, nearest last: the radius must keep the max */
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
-		'latitude' => '-33.8688', 'longitude' => '151.2093')),
-	gpsmap_test_row(array('id' => '3', 'hostname' => '10.5.0.3', 'host_template_id' => '20', 'groupnum' => '1',
-		'latitude' => '51.5080', 'longitude' => '-0.1280')),
-);
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	// furthest member listed first, nearest last: the radius must keep the max
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
+		'latitude'           => '-33.8688', 'longitude' => '151.2093']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '10.5.0.3', 'host_template_id' => '20', 'groupnum' => '1',
+		'latitude'           => '51.5080', 'longitude' => '-0.1280']),
+];
 region('all');
 assert_true('coverageXML: radius keeps the furthest member, not the last', gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))) > 1000.0);
 
-/* A device with coverage switched off is ignored by the overlay. */
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
-		'GPScoverage' => '', 'latitude' => '-33.8688', 'longitude' => '151.2093')),
-);
+// A device with coverage switched off is ignored by the overlay.
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
+		'GPScoverage'        => '', 'latitude' => '-33.8688', 'longitude' => '151.2093']),
+];
 region('all');
 assert_equal('coverageXML: coverage-off devices are ignored', 0.0, gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))));
 
+// ------------------------------------------------------------------
+// Single-pass loading: one query and one DNS pass for the whole cycle
+// ------------------------------------------------------------------
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.1.9.4', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '192.168.1.5', 'host_template_id' => '20']),
+];
+
+// No mapped devices at all is a normal state on a fresh install.
+$savedHosts                           = $GLOBALS['gpsmap_stub_rows']['hosts'];
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+assert_equal('load: empty result set yields empty groups', [[], []], gpsmap_load_devices(true));
+$GLOBALS['gpsmap_stub_rows']['hosts'] = $savedHosts;
+
+$loaded = gpsmap_load_devices(true);
+assert_equal('load: towers separated', 1, cacti_sizeof($loaded[0]));
+assert_equal('load: devices separated', 2, cacti_sizeof($loaded[1]));
+assert_equal('load: iprange holds the resolved address', '10.1.2.3', $loaded[0][0]->iprange);
+
+$prefixes = gpsmap_subnet_prefixes($loaded);
+assert_equal('prefixes: every depth, de-duplicated', ['10.', '10.1.', '10.1.2.', '10.1.9.', '192.', '192.168.', '192.168.1.'], $prefixes);
+assert_equal('prefixes: empty set yields none', [], gpsmap_subnet_prefixes([[], []]));
+
+/* IPv6 uses filename-safe reversible tokens while remaining in the same
+ * three-level navigation model. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '21', 'hostname' => '2001:db8:1234::5', 'host_template_id' => '20']),
+];
+$v6loaded = gpsmap_load_devices(true);
+assert_equal('ipv6: literal address is mapped', 1, cacti_sizeof($v6loaded[1]));
+assert_equal('ipv6: safe prefixes', ['v6-16-2001', 'v6-32-20010db8', 'v6-48-20010db81234'], gpsmap_subnet_prefixes($v6loaded));
+assert_equal('ipv6: token has a readable label', '2001:db8::/32', gpsmap_ipv6_prefix_label('v6-32-20010db8'));
+assert_true('ipv6: prefix membership', gpsmap_ipv6_prefix_contains('v6-32-20010db8', '2001:db8:ffff::1'));
+assert_false('ipv6: rejects another prefix', gpsmap_ipv6_prefix_contains('v6-32-20010db8', '2001:db9::1'));
+assert_equal('ipv6: invalid token has no label', null, gpsmap_ipv6_prefix_label('v6-31-nope'));
+assert_equal('ipv6: wrong token length has no label', null, gpsmap_ipv6_prefix_label('v6-32-2001'));
+assert_equal('ipv6: invalid address has no token', null, gpsmap_ipv6_prefix_token('nope', 32));
+assert_equal('ipv6: unsupported prefix length has no token', null, gpsmap_ipv6_prefix_token('2001:db8::1', 64));
+assert_false('ipv6: malformed prefix never matches', gpsmap_ipv6_prefix_contains('not-a-prefix', '2001:db8::1'));
+assert_false('ipv6: short prefix token never matches', gpsmap_ipv6_prefix_contains('v6-32-2001', '2001:db8::1'));
+assert_equal('artefact: invalid name falls back safely', 'all', gpsmap_artifact_stem('../escape'));
+
+gpsmap_render_region($v6loaded, 'v6-32-20010db8');
+assert_true('ipv6: safe artefact filename is written', file_exists(gpsmap_xml_path('v6-32-20010db8', 'xml')));
+assert_contains('ipv6: marker survives drilldown', 'id="21"', file_get_contents(gpsmap_xml_path('v6-32-20010db8', 'xml')));
+
+gpsmap_render_region($v6loaded, 'v6-48-20010db81234');
+assert_contains('ipv6: deepest level links to Device graphs', 'host_id=21',
+	file_get_contents($root . '/plugins/gpsmap/XML/v6-48-20010db81234-top.html'));
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '24', 'hostname' => '10.20.30.40', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '25', 'hostname' => '2001:db8:abcd::1', 'description' => 'IPv6 only', 'host_template_id' => '20']),
+];
+$mixed = gpsmap_load_devices(true);
+gpsmap_render_region($mixed, 'all');
+assert_contains('dual stack: all view includes IPv4', 'id="24"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_contains('dual stack: all view includes IPv6', 'id="25"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+gpsmap_render_region($mixed, '10.20');
+assert_not_contains('dual stack: IPv4 drilldown hides IPv6', 'id="25"', file_get_contents(gpsmap_xml_path('10.20', 'xml')));
+assert_not_contains('dual stack: IPv4 KML hides IPv6', '<name>IPv6 only</name>',
+	file_get_contents(gpsmap_xml_path('10.20', 'kml')));
+gpsmap_render_region($mixed, 'v6-32-20010db9');
+assert_not_contains('dual stack: nonmatching IPv6 prefix is hidden', 'id="25"',
+	file_get_contents(gpsmap_xml_path('v6-32-20010db9', 'xml')));
+
+// A configured hostname consumes only a cached value during the poll.
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '22', 'hostname' => 'router.example', 'cached_address' => '2001:db8::22', 'host_template_id' => '20']),
+];
+assert_equal('dns cache: cached hostname is mapped without a lookup', 1, cacti_sizeof(gpsmap_load_devices(true)[1]));
+
+/* thold stays optional; when enabled an alerting, otherwise-up Device receives
+ * the alert marker state while disabled/down precedence stays intact. */
+$GLOBALS['gpsmap_stub_plugins']       = ['thold'];
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '23', 'hostname' => '10.2.3.4', 'thold_alarm' => '1']),
+];
+assert_equal('thold: alert overrides healthy status', 'alert', gpsmap_load_devices(true)[0][0]->status);
+gpsmap_render_region(gpsmap_load_devices(true), 'all');
+assert_contains('thold: alert reaches XML', 'status="alert"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+$GLOBALS['gpsmap_stub_missing_tables'] = ['plugin_gpsmap_dns_cache', 'thold_data'];
+assert_equal('soft dependencies: missing optional tables keep literal Devices', 1, cacti_sizeof(gpsmap_load_devices(true)[0]));
+$GLOBALS['gpsmap_stub_missing_tables'] = [];
+$GLOBALS['gpsmap_stub_plugins']        = [];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = $savedHosts;
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+
+// Rendering mutates the shared set, so it must be restored between subnets.
+gpsmap_render_region($loaded, '10.1.2.');
+$hidden = 0;
+
+foreach ($loaded as $g) {
+	foreach ($g as $h) {
+		if ($h->showMap == 0) {
+			$hidden++;
+		}
+	}
+}
+assert_true('render: a narrow subnet hides the others', $hidden > 0);
+
+gpsmap_render_region($loaded, 'all');
+$hidden = 0;
+
+foreach ($loaded as $g) {
+	foreach ($g as $h) {
+		if ($h->showMap == 0) {
+			$hidden++;
+		}
+	}
+}
+assert_equal('render: state is reset before each subnet', 0, $hidden);
+
+// Reusing the set must give the same bytes as rendering it fresh.
+gpsmap_render_region($loaded, '10.1.2.');
+$reused = file_get_contents(gpsmap_xml_path('10.1.2.', 'xml'));
+region('10.1.2.');
+assert_equal('render: reused set matches a fresh load', $reused, file_get_contents(gpsmap_xml_path('10.1.2.', 'xml')));
+
+// ------------------------------------------------------------------
+// Atomic writes
+// ------------------------------------------------------------------
+
+$xmldir = $root . '/plugins/gpsmap/XML';
+assert_equal('write: leaves no temp files behind', [], preg_grep('/\.tmp$/', scandir($xmldir)));
+
+/* Prefix de-duplication must stay correct now that it is keyed rather than
+ * searched: many Devices in one subnet still yield one prefix per depth. */
+$dupHosts = [];
+
+for ($i = 1; $i <= 5; $i++) {
+	$dupHosts[] = gpsmap_test_row(['id' => (string) (60 + $i), 'hostname' => '10.3.3.' . $i]);
+}
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = $dupHosts;
+
+$dupPrefixes = gpsmap_subnet_prefixes(gpsmap_load_devices(true));
+
+assert_equal('prefixes: repeated addresses collapse', ['10.', '10.3.', '10.3.3.'], $dupPrefixes);
+assert_equal('prefixes: no duplicates survive', count($dupPrefixes), count(array_unique($dupPrefixes)));
+
+/* rename() into an occupied directory name fails, exercising the staged-write
+ * rollback: the temp file is removed and the failure is logged. */
+$blocked = $xmldir . '/occupied';
+@mkdir($blocked, 0700, true);
+file_put_contents($blocked . '/child', 'x');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+assert_false('write: failed rename returns false', gpsmap_write_file($blocked, 'body'));
+assert_true('write: failed rename is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
+assert_equal('write: failed rename leaves no temp file', [], preg_grep('/occupied\..*\.tmp$/', scandir($xmldir)));
+
+/* A short write must not be renamed into place: the previous document has to
+ * survive and the failure has to be logged. */
+$target = $xmldir . '/shortwrite.xml';
+file_put_contents($target, 'original');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+$full                       = str_repeat('x', 64);
+
+assert_false('write: short write returns false', gpsmap_write_file('gpsmapshort://target', $full));
+assert_true('write: short write is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
+
+assert_equal('write: previous document survives a failure', 'original', file_get_contents($target));
+
 /* Two Devices resolving to one address must yield one graph link, not two.
  * The de-duplication guard used to test a different string than it stored. */
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
-$GLOBALS['gpsmap_stub_rows']['hosts']  = array(
-	gpsmap_test_row(array('id' => '11', 'hostname' => '10.4.4.4', 'host_template_id' => '20')),
-	gpsmap_test_row(array('id' => '12', 'hostname' => '10.4.4.4', 'host_template_id' => '20')),
-);
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '11', 'hostname' => '10.4.4.4', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '12', 'hostname' => '10.4.4.4', 'host_template_id' => '20']),
+];
 region('10.4.4.');
 $deepest = file_get_contents($root . '/plugins/gpsmap/XML/10.4.4-top.html');
 assert_equal('region: one link per address at the deepest level', 1, substr_count($deepest, 'graph_view.php'));
 
-/* Disk pressure must not publish a truncated document while reporting success. */
-$GLOBALS['gpsmap_stub_log'] = array();
+/* Overwriting an existing artefact is the normal case: the poller rewrites the
+ * same names every cycle. */
+$overwrite = gpsmap_xml_path('overwrite-probe', 'xml');
+assert_true('write: first write creates the file', gpsmap_write_file($overwrite, 'first'));
+assert_true('write: second write replaces it', gpsmap_write_file($overwrite, 'second'));
+assert_equal('write: contents are the newer document', 'second', file_get_contents($overwrite));
+assert_equal('write: no temp files survive', [],
+	preg_grep('/overwrite-probe\..*\.tmp$/', scandir(dirname($overwrite))));
+
+// Pruning is age based and restricted to names gpsmap owns.
+$staleMap = gpsmap_xml_path('10.99', 'xml');
+$freshMap = gpsmap_xml_path('10.98', 'xml');
+$foreign  = dirname($staleMap) . '/operator-note.txt';
+file_put_contents($staleMap, 'stale');
+file_put_contents($freshMap, 'fresh');
+file_put_contents($foreign, 'keep');
+touch($staleMap, time() - 1000);
+assert_equal('prune: removes one stale generated artefact', 1, gpsmap_prune_artifacts(time() - 500));
+assert_false('prune: stale generated artefact is gone', file_exists($staleMap));
+assert_true('prune: fresh generated artefact remains', file_exists($freshMap));
+assert_true('prune: foreign file remains', file_exists($foreign));
+
+/* A failed rename must leave the previous document in place rather than
+ * deleting it and hoping the retry works. */
+$xd   = $root . '/plugins/gpsmap/XML';
+$live = $xd . '/rename-guard.xml';
+file_put_contents($live, 'previous');
+@mkdir($xd . '/rename-guard-dir', 0700, true);
+file_put_contents($xd . '/rename-guard-dir/child', 'x');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+assert_false('write: a failed rename reports failure', gpsmap_write_file($xd . '/rename-guard-dir', 'body'));
+assert_equal('write: the previous document is untouched', 'previous', file_get_contents($live));
+
+// Disk pressure must not publish a truncated document while reporting success.
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('write: a short write fails', gpsmap_write_file('gpsmapshort://target', str_repeat('x', 64)));
 assert_true('write: a short write is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
 
-/* A failed rename must roll back rather than leave a stray temp file. */
+// A failed rename must roll back rather than leave a stray temp file.
 $blocked = gpsmap_test_tmpdir() . '/plugins/gpsmap/XML/occupied';
 @mkdir($blocked, 0700, true);
 file_put_contents($blocked . '/child', 'x');
-$GLOBALS['gpsmap_stub_log'] = array();
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('write: a failed rename fails', gpsmap_write_file($blocked, 'body'));
 assert_true('write: a failed rename is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
-assert_equal('write: a failed rename leaves no temp file', array(),
+assert_equal('write: a failed rename leaves no temp file', [],
 	preg_grep('/occupied\..*\.tmp$/', scandir(gpsmap_test_tmpdir() . '/plugins/gpsmap/XML')));
 
 /* The Display Disabled Devices setting has to reach the query.  It never did:
  * pollinginitial.php assigns $enableAll inside callRegion(), so the global
  * region() read was always null and the setting was inert. */
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(gpsmap_test_row(array('id' => '31', 'hostname' => '10.7.7.1')));
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [gpsmap_test_row(['id' => '31', 'hostname' => '10.7.7.1'])];
 
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = '';
 region('all');
@@ -289,14 +503,106 @@ function gpsmap_test_tower_radius(string $xml): ?float {
 region('all');
 assert_not_contains('enableAll on: query does not filter disabled Devices', 'h.disabled = ?', $GLOBALS['gpsmap_stub_host_sql']);
 
-/* And it must not depend on a global the caller happens to have set. */
-$GLOBALS['enableAll'] = '';
+// And it must not depend on a global the caller happens to have set.
+$GLOBALS['enableAll']                                = '';
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('all');
 assert_not_contains('enableAll: a stale global does not override the setting', 'h.disabled = ?', $GLOBALS['gpsmap_stub_host_sql']);
 unset($GLOBALS['enableAll']);
 
-/* calcMeters is the retained deprecated alias. */
+/* A failed Device query and an estate with no mapped Devices both arrive as an
+ * empty set, but only the first is a reason to withhold publication.  Treating
+ * them alike meant a fresh install never got an all.xml at all. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = false;
+gpsmap_load_devices(true);
+assert_true('load: a failed query is reported', $GLOBALS['gpsmap_load_failed']);
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+gpsmap_load_devices(true);
+assert_false('load: an empty estate is not a failure', $GLOBALS['gpsmap_load_failed']);
+
+// An empty estate still publishes, so the map reflects reality.
+$emptyXml = gpsmap_xml_path('empty-estate', 'xml');
+gpsmap_render_region([[], []], 'empty-estate');
+assert_true('render: an empty estate still writes its documents', file_exists($emptyXml));
+assert_contains('render: the empty document is well formed', '<markers>', file_get_contents($emptyXml));
+
+// The staged write keeps the destination's mode, which the web server relies on.
+$modeTarget = gpsmap_xml_path('mode-probe', 'xml');
+gpsmap_write_file($modeTarget, 'first');
+chmod($modeTarget, 0644);
+$before = fileperms($modeTarget) & 0777;
+gpsmap_write_file($modeTarget, 'second');
+assert_equal('write: the destination mode survives the rename', $before, fileperms($modeTarget) & 0777);
+
+/* gpsmap_poller_bottom() is the refactor's only production entry point, so it
+ * is exercised directly rather than only through region(). */
+require_once __DIR__ . '/../includes/polling.php';
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '41', 'hostname' => '10.8.1.1', 'host_template_id' => '10']),
+	gpsmap_test_row(['id' => '42', 'hostname' => '10.8.2.2', 'host_template_id' => '20']),
+];
+$GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
+$GLOBALS['gpsmap_stub_settings']['path_php_binary']  = '/usr/bin/php';
+$GLOBALS['gpsmap_stub_log']                          = [];
+$GLOBALS['gpsmap_stub_background']                   = [];
+
+gpsmap_poller_bottom();
+
+assert_true('poller: publishes the top level', file_exists(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: publishes a subnet', file_exists(gpsmap_xml_path('10.8.1', 'xml')));
+assert_true('poller: logs a stats line',
+	(bool) preg_grep('/GPSMAP STATS: Mapped:2 /', $GLOBALS['gpsmap_stub_log']));
+assert_true('poller: schedules DNS refresh outside the poller',
+	(bool) preg_grep('/gpsmap_dns\.php$/', array_column($GLOBALS['gpsmap_stub_background'], 1)));
+
+// Resolver/cache helpers are deterministic under an injected lookup.
+assert_equal('dns: literal bypasses lookup', '192.0.2.1', gpsmap_resolve_hostname('192.0.2.1'));
+assert_equal('dns: accepts AAAA answers', '2001:db8::9', gpsmap_resolve_hostname('router.example',
+	static fn (string $name): array => [['ipv6' => '2001:db8::9']]));
+assert_equal('dns: failed lookup is empty', '', gpsmap_resolve_hostname('missing.example',
+	static fn (string $name): bool => false));
+assert_equal('dns: invalid answers are empty', '', gpsmap_resolve_hostname('bad.example',
+	static fn (string $name): array => [['ip' => 'not-an-ip']]));
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [
+	['hostname' => '192.0.2.2'],
+	['hostname' => 'localhost.invalid'],
+];
+$GLOBALS['gpsmap_stub_execute'] = [];
+assert_equal('dns: refresh skips literal rows', 1, gpsmap_refresh_dns_cache(
+	static fn (string $name): string => '2001:db8::10'));
+assert_equal('dns: refresh writes one cache row', 1, count($GLOBALS['gpsmap_stub_execute']));
+assert_contains('dns: a failed refresh preserves the last-known address',
+	'IF(VALUES(address) = "", address, VALUES(address))', $GLOBALS['gpsmap_stub_execute'][0][0]);
+
+// A failed Device query must leave the published map alone.
+file_put_contents(gpsmap_xml_path('all', 'xml'), '<markers><marker id="99"/></markers>');
+$GLOBALS['gpsmap_stub_rows']['hosts'] = false;
+$GLOBALS['gpsmap_stub_log']           = [];
+
+gpsmap_poller_bottom();
+
+assert_contains('poller: a failed query keeps the previous map', 'id="99"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: the failure is logged',
+	(bool) preg_grep('/could not read the Device list/', $GLOBALS['gpsmap_stub_log']));
+
+/* An estate with no mapped Devices still publishes, so a new install is not
+ * left fetching a 404 forever. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+$GLOBALS['gpsmap_stub_log']           = [];
+
+gpsmap_poller_bottom();
+
+assert_not_contains('poller: an empty estate republishes', 'id="99"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: the empty estate is explained',
+	(bool) preg_grep('/no Devices to map/', $GLOBALS['gpsmap_stub_log']));
+
+// calcMeters is the retained deprecated alias.
 assert_equal('calcMeters: delegates to calcKm', calcKm(1.0, 2.0, 3.0, 4.0), calcMeters(1.0, 2.0, 3.0, 4.0));
 
 if (!defined('GPSMAP_TEST_SUITE')) {
diff --git a/tests/test_upgrade.php b/tests/test_upgrade.php
new file mode 100644
index 0000000..a92f967
--- /dev/null
+++ b/tests/test_upgrade.php
@@ -0,0 +1,195 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | The upgrade path used to re-run every migration on each request because  |
+ | the version it gates on was never persisted.  On a large host table that |
+ | is a full rebuild plus a metadata lock, per page load.                   |
+ +-------------------------------------------------------------------------+
+*/
+
+if (PHP_SAPI !== 'cli') {
+	exit;
+}
+
+require_once __DIR__ . '/harness.php';
+
+/* Record the DDL the migration issues, and let set_config_option write to the
+ * same store read_config_option reads. */
+$GLOBALS['gpsmap_stub_ddl'] = [];
+
+if (!function_exists('db_execute')) {
+	function db_execute($sql, $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = $sql;
+
+		return empty($GLOBALS['gpsmap_stub_fail_ddl']);
+	}
+}
+
+if (!function_exists('db_execute_prepared')) {
+	function db_execute_prepared($sql, $params = [], $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = $sql;
+
+		if (isset($GLOBALS['gpsmap_stub_execute'])) {
+			$GLOBALS['gpsmap_stub_execute'][] = [$sql, $params];
+		}
+
+		return true;
+	}
+}
+
+if (!function_exists('set_config_option')) {
+	function set_config_option($name, $value) {
+		$GLOBALS['gpsmap_stub_settings'][$name] = (string) $value;
+	}
+}
+
+if (!function_exists('db_column_exists')) {
+	function db_column_exists($table, $column, $log = true, $db_conn = false) {
+		return empty($GLOBALS['gpsmap_stub_missing_column']);
+	}
+}
+
+if (!function_exists('db_table_exists')) {
+	function db_table_exists($table, $log = true, $db_conn = false) {
+		return true;
+	}
+}
+
+if (!function_exists('db_index_exists')) {
+	function db_index_exists($table, $index, $log = true, $db_conn = false) {
+		return $GLOBALS['gpsmap_stub_index_exists'] ?? true;
+	}
+}
+
+if (!function_exists('db_add_index')) {
+	function db_add_index($table, $type, $name, $columns, $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = 'ADD INDEX ' . $name;
+
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_db_add_column')) {
+	function api_plugin_db_add_column($plugin, $table, $column) {
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_db_table_create')) {
+	function api_plugin_db_table_create($plugin, $table, $data) {
+		return true;
+	}
+}
+
+gpsmap_test_use_tmp_root();
+$GLOBALS['config']['library_path'] = sys_get_temp_dir();
+file_put_contents(sys_get_temp_dir() . '/database.php', "<?php\n");
+
+require_once __DIR__ . '/../setup.php';
+require_once __DIR__ . '/../includes/setup/database.php';
+
+$info = plugin_gpsmap_version();
+
+// First run from an unknown previous version: the migrations fire.
+$GLOBALS['gpsmap_stub_ddl'] = [];
+gpsmap_upgrade_database('');
+$first = $GLOBALS['gpsmap_stub_ddl'];
+
+assert_true('upgrade: a fresh install runs the column migration', (bool) preg_grep('/ALTER TABLE host CHANGE COLUMN latitude/', $first));
+assert_equal('upgrade: no backticked literal default reaches MySQL', [], preg_grep('/SET DEFAULT `/', $first));
+
+// The version has to be persisted where gpsmap_check_upgrade() reads it.
+assert_equal(
+	'upgrade: version is persisted to the option the guard reads',
+	$info['version'],
+	read_config_option('plugin_gpsmap_version', true)
+);
+
+// Second run, now that the version matches: no DDL against host at all.
+$GLOBALS['gpsmap_stub_ddl'] = [];
+gpsmap_upgrade_database((string) $info['version']);
+
+assert_equal(
+	'upgrade: a current install issues no ALTER TABLE',
+	[],
+	preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl'])
+);
+
+// Pre-2.1 installs without the unique index get it added exactly once.
+$GLOBALS['gpsmap_stub_index_exists'] = false;
+$GLOBALS['gpsmap_stub_ddl']          = [];
+gpsmap_upgrade_database('2.0');
+assert_true('upgrade: missing unique index is added', (bool) preg_grep('/ADD INDEX templateID/', $GLOBALS['gpsmap_stub_ddl']));
+
+$GLOBALS['gpsmap_stub_index_exists'] = true;
+$GLOBALS['gpsmap_stub_ddl']          = [];
+gpsmap_upgrade_database('2.0');
+assert_equal('upgrade: existing index is not re-added', [], preg_grep('/ADD INDEX/', $GLOBALS['gpsmap_stub_ddl']));
+
+// And the guard itself now goes quiet.
+assert_true(
+	'upgrade: the guard is satisfied after one run',
+	$info['version'] == read_config_option('plugin_gpsmap_version', true)
+);
+
+/* A failed migration must not mark the plugin as current, or the upgrade never
+ * runs again and the schema stays behind silently. */
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version'] = '';
+$GLOBALS['gpsmap_stub_ddl']                               = [];
+$GLOBALS['gpsmap_stub_fail_ddl']                          = true;
+
+gpsmap_upgrade_database('');
+
+assert_equal('upgrade: a failed migration leaves the version unrecorded', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+assert_true('upgrade: the failure is logged',
+	str_contains(implode(' ', $GLOBALS['gpsmap_stub_log'] ?? []), 'did not complete'));
+
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = false;
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+gpsmap_upgrade_database('');
+assert_equal('upgrade: a successful migration records the version',
+	$info['version'], read_config_option('plugin_gpsmap_version', true));
+
+/* A failed migration must back off rather than retry from every page view, and
+ * must never record the version while the schema is behind. */
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = true;
+$GLOBALS['gpsmap_stub_log']                                           = [];
+
+gpsmap_upgrade_database('');
+
+assert_equal('upgrade: a failure never records the version', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+assert_true('upgrade: a backoff is recorded',
+	(int) read_config_option('plugin_gpsmap_upgrade_retry_after', true) > time());
+
+// While the backoff is live, no further DDL is attempted.
+$GLOBALS['gpsmap_stub_ddl'] = [];
+gpsmap_upgrade_database('');
+assert_equal('upgrade: the backoff suppresses the retry', [], $GLOBALS['gpsmap_stub_ddl']);
+
+// Once it expires and the cause clears, the upgrade completes and re-arms.
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = false;
+gpsmap_upgrade_database('');
+assert_equal('upgrade: recovery records the version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+assert_equal('upgrade: recovery clears the backoff', '0',
+	(string) read_config_option('plugin_gpsmap_upgrade_retry_after', true));
+
+// A missing host column means the schema work failed, whatever the helpers say.
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_missing_column']                                = true;
+gpsmap_upgrade_database('');
+assert_equal('upgrade: a missing column blocks the version write', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+$GLOBALS['gpsmap_stub_missing_column'] = false;
+
+if (!defined('GPSMAP_TEST_SUITE')) {
+	exit(gpsmap_test_summary());
+}