core: IP-Range-Scan Support (app.vars / default.vars) (#10038)

docs/guides/DEFAULTS_SYSTEM_GUIDE.md

@@ -434,12 +434,24 @@ var_unprivileged=1     # 0=privileged, 1=unprivileged
 #### Network
 ```bash
 var_brg=vmbr0          # Bridge interface
-var_net=veth           # Network driver
-var_gateway=192.168.1.1  # Default gateway
+var_net=dhcp           # dhcp, static IP/CIDR, or IP range (see below)
+var_gateway=192.168.1.1  # Default gateway (required for static IP)
 var_mtu=1500           # MTU size
 var_vlan=100           # VLAN ID
 ```
 
+#### IP Range Scanning
+
+You can specify an IP range instead of a static IP. The system will ping each IP in the range and automatically assign the first free IP:
+
+```bash
+# Format: START_IP/CIDR-END_IP/CIDR
+var_net=192.168.1.100/24-192.168.1.200/24
+var_gateway=192.168.1.1
+```
+
+This is useful for automated deployments where you want static IPs but don't want to track which IPs are already in use.
+
 #### System
 ```bash
 var_hostname=pihole    # Container name

docs/guides/UNATTENDED_DEPLOYMENTS.md

@@ -122,6 +122,31 @@ var_verbose=no \
 echo "✓ Container deployed successfully"
 ```
 
+### Using IP Range Scan for Automatic IP Assignment
+
+Instead of manually specifying static IPs, you can define an IP range. The system will automatically ping each IP and assign the first free one:
+
+```bash
+#!/bin/bash
+# deploy-with-ip-scan.sh - Auto-assign first free IP from range
+
+var_unprivileged=1 \
+var_cpu=4 \
+var_ram=4096 \
+var_hostname=web-server \
+var_net=192.168.1.100/24-192.168.1.150/24 \
+var_gateway=192.168.1.1 \
+  bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/debian.sh)"
+
+# The script will:
+# 1. Ping 192.168.1.100 - if responds, skip
+# 2. Ping 192.168.1.101 - if responds, skip
+# 3. Continue until first IP that doesn't respond
+# 4. Assign that IP to the container
+```
+
+> **Note**: IP range format is `START_IP/CIDR-END_IP/CIDR`. Both sides must include the same CIDR notation.
+
 ### Using App Defaults
 
 **Step 1: Create defaults once (interactive)**