fix(scripts): Besu fleet ops use load-project-env and scoped VMIDs

Prefer load-project-env over raw ip-addresses.conf; add --vmid/--apply patterns and safer dry-run defaults across fix-all-besu, static-nodes reload, node-list deploy, max-peers rollout, rolling upgrade, and permissions verification. Made-with: Cursor
2026-04-12 06:44:12 -07:00
parent cc6821ebad
commit 282256a387
6 changed files with 368 additions and 89 deletions
--- a/scripts/besu/fix-all-besu-nodes.sh
+++ b/scripts/besu/fix-all-besu-nodes.sh
@@ -1,42 +1,89 @@
 #!/usr/bin/env bash
-# Fix all Besu nodes: deploy canonical node lists, normalize config (TOML permissions path,
+# Fix selected Besu nodes: deploy canonical node lists, normalize config (TOML permissions path,
 # remove tx-pool-min-score, ensure genesis), then restart Besu.
-# Run from project root. Usage: bash scripts/besu/fix-all-besu-nodes.sh [--dry-run] [--no-restart]
+# Run from project root.
+# Usage:
+#   bash scripts/besu/fix-all-besu-nodes.sh
+#   bash scripts/besu/fix-all-besu-nodes.sh --vmid 2301 --no-restart
+#   bash scripts/besu/fix-all-besu-nodes.sh --apply --vmid 2301

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 cd "$PROJECT_ROOT"
-source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

-DRY_RUN=false
+DRY_RUN=true
 NO_RESTART=false
-for arg in "${@:-}"; do
-  [[ "$arg" == "--dry-run" ]] && DRY_RUN=true
-  [[ "$arg" == "--no-restart" ]] && NO_RESTART=true
-done
-
-# Same host/VMID as deploy-besu-node-lists-to-all.sh
-declare -A HOST_BY_VMID
-for v in 1000 1001 1002 1500 1501 1502 2101 2500 2501 2502 2503 2504 2505; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
-
-BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 2101 2102 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403 2500 2501 2502 2503 2504 2505)
+TARGET_VMIDS=()
+BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 2101 2102 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403)
 STATIC="${PROJECT_ROOT}/config/besu-node-lists/static-nodes.json"
 PERMS="${PROJECT_ROOT}/config/besu-node-lists/permissions-nodes.toml"
 SSH_OPTS="-o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new"

+usage() {
+  cat <<'EOF'
+Usage: bash scripts/besu/fix-all-besu-nodes.sh [--apply] [--dry-run] [--no-restart] [--vmid <N>]
+
+Options:
+  --dry-run     Print intended actions only (default)
+  --apply       Perform fixes on selected nodes
+  --no-restart  Skip restart step
+  --vmid <N>    Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --apply)
+      DRY_RUN=false
+      shift
+      ;;
+    --no-restart)
+      NO_RESTART=true
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}
+
 if [[ ! -f "$STATIC" ]] || [[ ! -f "$PERMS" ]]; then
  echo "ERROR: Missing $STATIC or $PERMS" >&2
  exit 1
 fi

-echo "=== Fix all Besu nodes ==="
+echo "=== Fix selected Besu nodes ==="
 echo "  1. Deploy node lists to all nodes"
 echo "  2. Fix config on each node (permissions TOML path, remove tx-pool-min-score, genesis)"
-echo "  3. Restart Besu on all nodes"
+echo "  3. Restart Besu on selected nodes"
 if $DRY_RUN; then echo "  [DRY-RUN]"; fi
 if $NO_RESTART; then echo "  [NO-RESTART]"; fi
 echo ""
@@ -44,14 +91,19 @@ echo ""
 # Step 1: Deploy node lists
 echo "--- Step 1: Deploy static-nodes.json and permissions-nodes.toml ---"
 if ! $DRY_RUN; then
-  bash "${PROJECT_ROOT}/scripts/deploy-besu-node-lists-to-all.sh" 2>/dev/null || true
+  deploy_args=(--apply)
+  for vmid in "${TARGET_VMIDS[@]}"; do
+    deploy_args+=(--vmid "$vmid")
+  done
+  bash "${PROJECT_ROOT}/scripts/deploy-besu-node-lists-to-all.sh" "${deploy_args[@]}" 2>/dev/null || true
 fi
 echo ""

 # Step 2: Fix config on each running node (permissions path, remove tx-pool-min-score, genesis)
 echo "--- Step 2: Fix config on each node ---"
 for vmid in "${BESU_VMIDS[@]}"; do
-  host="${HOST_BY_VMID[$vmid]:-}"
+  selected_vmid "$vmid" || continue
+  host="$(get_host_for_vmid "$vmid")"
  [[ -z "$host" ]] && continue
  running=$(ssh $SSH_OPTS "root@$host" "pct status $vmid 2>/dev/null | awk '{print \$2}'" 2>/dev/null || echo "")
  if [[ "$running" != "running" ]]; then
@@ -69,12 +121,16 @@ echo ""
 # Step 3: Restart Besu
 if $NO_RESTART; then
  echo "--- Step 3: skipped (--no-restart) ---"
-  echo "Run: bash scripts/besu/restart-besu-reload-node-lists.sh"
+  echo "Run: bash scripts/besu/restart-besu-reload-node-lists.sh --apply [--vmid <N>]"
  exit 0
 fi
-echo "--- Step 3: Restart Besu on all nodes ---"
+echo "--- Step 3: Restart Besu on selected nodes ---"
 if ! $DRY_RUN; then
-  bash "${PROJECT_ROOT}/scripts/besu/restart-besu-reload-node-lists.sh" 2>/dev/null || true
+  restart_args=(--apply)
+  for vmid in "${TARGET_VMIDS[@]}"; do
+    restart_args+=(--vmid "$vmid")
+  done
+  bash "${PROJECT_ROOT}/scripts/besu/restart-besu-reload-node-lists.sh" "${restart_args[@]}" 2>/dev/null || true
 fi
 echo ""
 echo "Done."
--- a/scripts/besu/restart-besu-reload-node-lists.sh
+++ b/scripts/besu/restart-besu-reload-node-lists.sh
@@ -1,30 +1,75 @@
 #!/usr/bin/env bash
-# Restart Besu on all nodes that receive the node-list deploy so they reload
+# Restart Besu on selected nodes that receive the node-list deploy so they reload
 # /etc/besu/static-nodes.json and /etc/besu/permissions-nodes.toml.
-# Uses same host/VMID list as scripts/deploy-besu-node-lists-to-all.sh.
+# Uses the shared live VMID placement map.
 #
-# Usage: bash scripts/besu/restart-besu-reload-node-lists.sh [--dry-run]
+# Usage:
+#   bash scripts/besu/restart-besu-reload-node-lists.sh
+#   bash scripts/besu/restart-besu-reload-node-lists.sh --vmid 2301
+#   bash scripts/besu/restart-besu-reload-node-lists.sh --apply --vmid 2301

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

 SSH_OPTS="-o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=accept-new"

-DRY_RUN=false
-[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+DRY_RUN=true
+TARGET_VMIDS=()

-# Same VMID -> host as deploy-besu-node-lists-to-all.sh
-declare -A HOST_BY_VMID
-for v in 1000 1001 1002 1500 1501 1502 2101 2103; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 1509 1510 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
+usage() {
+  cat <<'EOF'
+Usage: bash scripts/besu/restart-besu-reload-node-lists.sh [--apply] [--dry-run] [--vmid <N>]
+
+Options:
+  --dry-run     Print intended actions only (default)
+  --apply       Restart Besu on selected nodes
+  --vmid <N>    Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --apply)
+      DRY_RUN=false
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done

 BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 2101 2102 2103 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403)

-echo "Restarting Besu on all nodes (to reload static-nodes.json and permissions-nodes.toml)"
+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}
+
+echo "Restarting Besu on selected nodes (to reload static-nodes.json and permissions-nodes.toml)"
 if $DRY_RUN; then echo "  [dry-run]"; fi
 echo ""

@@ -32,7 +77,8 @@ ok=0
 skip=0
 fail=0
 for vmid in "${BESU_VMIDS[@]}"; do
-  host="${HOST_BY_VMID[$vmid]:-}"
+  selected_vmid "$vmid" || continue
+  host="$(get_host_for_vmid "$vmid")"
  [[ -z "$host" ]] && continue
  running=$(ssh $SSH_OPTS "root@$host" "pct status $vmid 2>/dev/null | awk '{print \$2}'" 2>/dev/null || echo "")
  if [[ "$running" != "running" ]]; then
@@ -45,7 +91,7 @@ for vmid in "${BESU_VMIDS[@]}"; do
    ((ok++)) || true
    continue
  fi
-  # Detect Besu unit: besu-validator, besu-sentry, besu-rpc, or generic besu.service (1505-1508, 2500-2505)
+  # Detect Besu unit: besu-validator, besu-sentry, besu-rpc, or generic besu.service.
  result=$(ssh $SSH_OPTS "root@$host" "timeout 180 pct exec $vmid -- bash -c 'svc=\$(systemctl list-units --type=service --no-legend 2>/dev/null | grep -iE \"besu-validator|besu-sentry|besu-rpc|besu\\.service\" | head -1 | awk \"{print \\\$1}\"); if [ -n \"\$svc\" ]; then systemctl restart \"\$svc\" && echo \"OK:\$svc\"; else echo \"NONE\"; fi'" 2>/dev/null || echo "FAIL")
  if [[ "$result" == OK:* ]]; then
    echo "VMID $vmid @ $host: restarted (${result#OK:})"
--- a/scripts/deploy-besu-node-lists-to-all.sh
+++ b/scripts/deploy-besu-node-lists-to-all.sh
@@ -1,20 +1,61 @@
 #!/usr/bin/env bash
-# Deploy canonical static-nodes.json and permissions-nodes.toml to ALL Besu nodes.
+# Deploy canonical static-nodes.json and permissions-nodes.toml to selected Besu nodes.
 # Source: config/besu-node-lists/ (single source of truth).
 # Ensures identical node lists on every validator, sentry, and RPC for correct permissioning.
 #
-# Usage: ./scripts/deploy-besu-node-lists-to-all.sh [--dry-run]
+# Usage:
+#   ./scripts/deploy-besu-node-lists-to-all.sh
+#   ./scripts/deploy-besu-node-lists-to-all.sh --vmid 2301
+#   ./scripts/deploy-besu-node-lists-to-all.sh --apply --vmid 2301

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

 SSH_OPTS=(-o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=accept-new)

-DRY_RUN=false
-[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+DRY_RUN=true
+TARGET_VMIDS=()
+
+usage() {
+  cat <<'EOF'
+Usage: ./scripts/deploy-besu-node-lists-to-all.sh [--apply] [--dry-run] [--vmid <N>]
+
+Options:
+  --dry-run     Print intended actions only (default)
+  --apply       Push node-list files to selected nodes
+  --vmid <N>    Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --apply)
+      DRY_RUN=false
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done

 STATIC="${PROJECT_ROOT}/config/besu-node-lists/static-nodes.json"
 PERMS="${PROJECT_ROOT}/config/besu-node-lists/permissions-nodes.toml"
@@ -27,18 +68,19 @@ if [[ ! -f "$STATIC" ]] || [[ ! -f "$PERMS" ]]; then
    exit 1
 fi

-# VMID -> Proxmox host (per BESU_VMIDS_FROM_PROXMOX / list-besu-vmids-from-proxmox.sh)
-declare -A HOST_BY_VMID
-# r630-01 (192.168.11.11) — 2500-2505 removed (destroyed; see ALL_VMIDS_ENDPOINTS.md)
-for v in 1000 1001 1002 1500 1501 1502 2101 2103; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-# r630-02 (192.168.11.12)
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-# r630-03 (192.168.11.13)
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 1509 1510 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
-
 BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 2101 2102 2103 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403)

-echo "Deploying Besu node lists from config/besu-node-lists/ to all nodes"
+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}
+
+echo "Deploying Besu node lists from config/besu-node-lists/ to selected nodes"
 echo "  static-nodes.json      -> /etc/besu/static-nodes.json"
 echo "  permissions-nodes.toml -> /etc/besu/permissions-nodes.toml"
 echo ""
@@ -46,7 +88,8 @@ echo ""
 # Group by host to minimize scp/ssh
 declare -A VMIDS_ON_HOST
 for vmid in "${BESU_VMIDS[@]}"; do
-    host="${HOST_BY_VMID[$vmid]:-}"
+    selected_vmid "$vmid" || continue
+    host="$(get_host_for_vmid "$vmid")"
    [[ -z "$host" ]] && continue
    VMIDS_ON_HOST[$host]+=" $vmid"
 done
@@ -72,4 +115,4 @@ done

 echo ""
 echo "Done. To reload static-nodes.json and permissions-nodes.toml immediately, run:"
-echo "  bash scripts/besu/restart-besu-reload-node-lists.sh"
+echo "  bash scripts/besu/restart-besu-reload-node-lists.sh --apply [--vmid <N>]"
--- a/scripts/maintenance/set-all-besu-max-peers-32.sh
+++ b/scripts/maintenance/set-all-besu-max-peers-32.sh
@@ -1,34 +1,80 @@
 #!/usr/bin/env bash
-# Set max-peers=40 in Besu config on all running Besu nodes (in-place sed).
+# Set max-peers=40 in Besu config on selected running Besu nodes (in-place sed).
 # Run after repo configs are updated; then restart Besu with restart-besu-reload-node-lists.sh.
 # See: docs/08-monitoring/PEER_CONNECTIONS_PLAN.md
 #
-# Usage: ./scripts/maintenance/set-all-besu-max-peers-32.sh [--dry-run]
+# Usage:
+#   ./scripts/maintenance/set-all-besu-max-peers-32.sh
+#   ./scripts/maintenance/set-all-besu-max-peers-32.sh --vmid 2301
+#   ./scripts/maintenance/set-all-besu-max-peers-32.sh --apply --vmid 2301
 # Requires: SSH to Proxmox hosts (r630-01, r630-02, r630-03).

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-[[ -f "${PROJECT_ROOT}/config/ip-addresses.conf" ]] && source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

-DRY_RUN=false
-[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+DRY_RUN=true
+TARGET_VMIDS=()
 TARGET_MAX_PEERS=40
-
-declare -A HOST_BY_VMID
-for v in 1000 1001 1002 1500 1501 1502 2101 2103 2500 2501 2502 2503 2504 2505; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
-
-BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 2101 2102 2103 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403 2500 2501 2502 2503 2504 2505)
+BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 2101 2102 2103 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403)
 SSH_OPTS="-o ConnectTimeout=8 -o StrictHostKeyChecking=accept-new"

+usage() {
+  cat <<'EOF'
+Usage: ./scripts/maintenance/set-all-besu-max-peers-32.sh [--apply] [--dry-run] [--vmid <N>]
+
+Options:
+  --dry-run     Print intended actions only (default)
+  --apply       Update max-peers on selected nodes
+  --vmid <N>    Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --apply)
+      DRY_RUN=false
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}
+
 echo "Set max-peers=${TARGET_MAX_PEERS} on all Besu nodes (dry-run=$DRY_RUN)"
 echo ""

 for vmid in "${BESU_VMIDS[@]}"; do
-  host="${HOST_BY_VMID[$vmid]:-}"
+  selected_vmid "$vmid" || continue
+  host="$(get_host_for_vmid "$vmid")"
  [[ -z "$host" ]] && continue
  running=$(ssh $SSH_OPTS "root@$host" "pct status $vmid 2>/dev/null | awk '{print \$2}'" 2>/dev/null || echo "")
  if [[ "$running" != "running" ]]; then
@@ -62,5 +108,5 @@ for vmid in "${BESU_VMIDS[@]}"; do
 done

 echo ""
-echo "Done. Restart Besu on all nodes to apply: ./scripts/besu/restart-besu-reload-node-lists.sh"
+echo "Done. Restart Besu on selected nodes to apply: ./scripts/besu/restart-besu-reload-node-lists.sh --apply [--vmid <N>]"
 echo ""
--- a/scripts/upgrade-besu-all-nodes.sh
+++ b/scripts/upgrade-besu-all-nodes.sh
@@ -1,18 +1,20 @@
 #!/usr/bin/env bash
-# Upgrade all running Besu containers to the requested version.
+# Upgrade selected Besu containers to the requested version.
 # Installs Java 21 where needed, preserves the previous /opt/besu-* directory for rollback,
 # and restarts the detected Besu systemd unit in each container.
 #
 # Usage:
 #   bash scripts/upgrade-besu-all-nodes.sh
-#   bash scripts/upgrade-besu-all-nodes.sh --dry-run
+#   bash scripts/upgrade-besu-all-nodes.sh --vmid 2301
 #   BESU_VERSION=25.12.0 bash scripts/upgrade-besu-all-nodes.sh
+#
+# Default is dry-run. Use --apply to mutate selected nodes.

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

 BESU_VERSION="${BESU_VERSION:-25.12.0}"
 BESU_TAR="besu-${BESU_VERSION}.tar.gz"
@@ -22,8 +24,46 @@ JAVA21_FALLBACK_URL="${JAVA21_FALLBACK_URL:-https://api.adoptium.net/v3/binary/l
 RPC_HTTP_MAX_ACTIVE_CONNECTIONS="${RPC_HTTP_MAX_ACTIVE_CONNECTIONS:-256}"
 RPC_WS_MAX_ACTIVE_CONNECTIONS="${RPC_WS_MAX_ACTIVE_CONNECTIONS:-256}"
 LOCAL_CACHE="${LOCAL_CACHE:-/tmp}"
-DRY_RUN=false
-[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=true
+DRY_RUN=true
+TARGET_VMIDS=()
+
+usage() {
+  cat <<'EOF'
+Usage: bash scripts/upgrade-besu-all-nodes.sh [--apply] [--dry-run] [--vmid <N>]
+
+Options:
+  --dry-run     Print intended actions only (default)
+  --apply       Perform the upgrade on selected nodes
+  --vmid <N>    Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    --apply)
+      DRY_RUN=false
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done

 SSH_OPTS=(-o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=accept-new)

@@ -38,11 +78,6 @@ log_ok() { echo -e "${GREEN}[OK]${NC} $1"; }
 log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
 log_err() { echo -e "${RED}[ERROR]${NC} $1"; }

-declare -A HOST_BY_VMID
-for v in 1000 1001 1002 1500 1501 1502 2101; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
-
 BESU_VMIDS=(
  1000 1001 1002 1003 1004
  1500 1501 1502 1503 1504 1505 1506 1507 1508
@@ -50,6 +85,16 @@ BESU_VMIDS=(
  2400 2401 2402 2403
 )

+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}
+
 host_ssh() {
  local host="$1"
  shift
@@ -224,7 +269,8 @@ TARBALL_PATH="$(ensure_tarball)"

 declare -A VMIDS_ON_HOST
 for vmid in "${BESU_VMIDS[@]}"; do
-  host="${HOST_BY_VMID[$vmid]:-}"
+  selected_vmid "$vmid" || continue
+  host="$(get_host_for_vmid "$vmid")"
  [[ -n "$host" ]] || continue
  VMIDS_ON_HOST[$host]+=" ${vmid}"
 done
--- a/scripts/verify/verify-static-permissions-on-all-besu-nodes.sh
+++ b/scripts/verify/verify-static-permissions-on-all-besu-nodes.sh
@@ -1,24 +1,65 @@
 #!/usr/bin/env bash
 # Confirm static-nodes.json and permissions-nodes.toml on each Besu node (deploy target: /etc/besu/).
-# Usage: bash scripts/verify/verify-static-permissions-on-all-besu-nodes.sh [--checksum]
+# Usage:
+#   bash scripts/verify/verify-static-permissions-on-all-besu-nodes.sh [--checksum]
+#   bash scripts/verify/verify-static-permissions-on-all-besu-nodes.sh --vmid 2301 [--checksum]
 #   --checksum: compare content hash to canonical (requires same files on all nodes).

 set -euo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+source "${PROJECT_ROOT}/scripts/lib/load-project-env.sh"

 STATIC_CANONICAL="${PROJECT_ROOT}/config/besu-node-lists/static-nodes.json"
 PERMS_CANONICAL="${PROJECT_ROOT}/config/besu-node-lists/permissions-nodes.toml"
 CHECKSUM=false
-[[ "${1:-}" = "--checksum" ]] && CHECKSUM=true
+TARGET_VMIDS=()

-# Same VMID -> host as deploy-besu-node-lists-to-all.sh
-declare -A HOST_BY_VMID
-for v in 1000 1001 1002 1500 1501 1502 2101 2420 2430 2440 2460 2470 2480; do HOST_BY_VMID[$v]="${PROXMOX_R630_01:-${PROXMOX_HOST_R630_01:-192.168.11.11}}"; done
-for v in 2201 2303 2305 2306 2307 2308 2401; do HOST_BY_VMID[$v]="${PROXMOX_R630_02:-${PROXMOX_HOST_R630_02:-192.168.11.12}}"; done
-for v in 1003 1004 1503 1504 1505 1506 1507 1508 1509 1510 2102 2301 2304 2400 2402 2403; do HOST_BY_VMID[$v]="${PROXMOX_R630_03:-${PROXMOX_HOST_R630_03:-192.168.11.13}}"; done
+usage() {
+  cat <<'EOF'
+Usage: bash scripts/verify/verify-static-permissions-on-all-besu-nodes.sh [--checksum] [--vmid <N>]
+
+Options:
+  --checksum   Compare remote content hash to canonical files
+  --vmid <N>   Limit to one VMID; repeatable
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --checksum)
+      CHECKSUM=true
+      shift
+      ;;
+    --vmid)
+      [[ $# -ge 2 ]] || { usage >&2; exit 2; }
+      TARGET_VMIDS+=("$2")
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+BESU_VMIDS=(1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 2101 2102 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403 2420 2430 2440 2460 2470 2480)
+
+selected_vmid() {
+  local vmid="$1"
+  [[ ${#TARGET_VMIDS[@]} -eq 0 ]] && return 0
+  local wanted
+  for wanted in "${TARGET_VMIDS[@]}"; do
+    [[ "$vmid" == "$wanted" ]] && return 0
+  done
+  return 1
+}

 SSH_OPTS="-o ConnectTimeout=6 -o StrictHostKeyChecking=no"
 CANONICAL_STATIC_SUM=""
@@ -40,8 +81,9 @@ STATIC_PATH="/etc/besu/static-nodes.json"
 PERMS_PATH="/etc/besu/permissions-nodes.toml"

 FAIL=0
-for vmid in 1000 1001 1002 1003 1004 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 2101 2102 2201 2301 2303 2304 2305 2306 2307 2308 2400 2401 2402 2403 2420 2430 2440 2460 2470 2480; do
-  host="${HOST_BY_VMID[$vmid]:-}"
+for vmid in "${BESU_VMIDS[@]}"; do
+  selected_vmid "$vmid" || continue
+  host="$(get_host_for_vmid "$vmid")"
  [[ -z "$host" ]] && continue
  run=$(ssh $SSH_OPTS root@$host "pct exec $vmid -- bash -c 's=\"\"; p=\"\"; [ -f $STATIC_PATH ] && s=\"OK\" || s=\"MISSING\"; [ -f $PERMS_PATH ] && p=\"OK\" || p=\"MISSING\"; echo \"\$s \$p\"' 2>/dev/null" || echo "SKIP SKIP")
  if [[ "$run" =~ "SKIP" ]]; then