Improve Proxmox authentication timeout diagnostics

netbox_vmware_importer/__init__.py

@@ -5,7 +5,7 @@ class VMwareImporterConfig(PluginConfig):
     name = "netbox_vmware_importer"
     verbose_name = "Virtualization Importer"
     description = "Synchronize VMware vSphere and Proxmox VE virtual machines into NetBox."
-    version = "0.2.1"
+    version = "0.2.2"
     author = "Internal NetBox Team"
     base_url = "vmware-importer"
     min_version = "4.4.0"

netbox_vmware_importer/models.py

@@ -241,6 +241,8 @@ class VCenterEndpoint(JobsMixin, NetBoxModel):
                 raise ValidationError({"auth_method": _("VMware endpoints currently support username/password authentication only.")})
 
         if self.provider == EndpointProviderChoices.PROVIDER_PROXMOX:
+            if "@" not in self.username:
+                raise ValidationError({"username": _("Proxmox usernames must include a realm, e.g. root@pam or user@pve.")})
             if self.auth_method == EndpointAuthMethodChoices.METHOD_API_TOKEN and not self.token_name:
                 raise ValidationError({"token_name": _("A token name is required for Proxmox API token authentication.")})
 

netbox_vmware_importer/sync.py

@@ -233,16 +233,21 @@ class ProxmoxClient:
         self.session = None
         self.base_url = f"https://{endpoint.host}:{endpoint.port}/api2/json"
         self.timeout = (10, endpoint.request_timeout_seconds or 120)
+        self.api_probe_succeeded = False
 
     def __enter__(self):
         if requests is None:
             raise ProxmoxConnectionError("requests is not installed in the NetBox Python environment.")
+        if "@" not in self.endpoint.username:
+            raise ProxmoxConnectionError("Proxmox username must include a realm, e.g. root@pam or user@pve.")
 
         self.session = requests.Session()
         self.session.verify = self.endpoint.validate_ssl
         if not self.endpoint.validate_ssl and InsecureRequestWarning is not None:
             requests.packages.urllib3.disable_warnings(category=InsecureRequestWarning)
 
+        self._probe_api_availability()
+
         if self.endpoint.auth_method == EndpointAuthMethodChoices.METHOD_API_TOKEN:
             token_id = self.endpoint.token_name if "!" in self.endpoint.token_name else f"{self.endpoint.username}!{self.endpoint.token_name}"
             self.session.headers.update({"Authorization": f"PVEAPIToken={token_id}={self.endpoint.password}"})
@@ -255,6 +260,10 @@ class ProxmoxClient:
         if self.session is not None:
             self.session.close()
 
+    def _probe_api_availability(self):
+        self._request("GET", "version")
+        self.api_probe_succeeded = True
+
     def _authenticate_with_password(self):
         response = self._request(
             "POST",
@@ -284,9 +293,18 @@ class ProxmoxClient:
             response = self.session.request(method, url, timeout=self.timeout, **kwargs)
             response.raise_for_status()
             return response
-        except requests.Timeout as exc:
+        except requests.ConnectTimeout as exc:
             raise ProxmoxConnectionError(
-                f"Proxmox API {method} {path} timed out after {self.timeout[1]} seconds."
+                f"Proxmox API {method} {path} connect timed out after {self.timeout[0]} seconds."
+            ) from exc
+        except requests.ReadTimeout as exc:
+            detail = f"Proxmox API {method} {path} read timed out after {self.timeout[1]} seconds."
+            if path == "access/ticket" and self.api_probe_succeeded:
+                detail += " API version endpoint responded, so the delay is likely in Proxmox authentication. Check username realm (e.g. root@pam), PAM/LDAP auth, two-factor auth, or use an API token."
+            raise ProxmoxConnectionError(detail) from exc
+        except requests.exceptions.SSLError as exc:
+            raise ProxmoxConnectionError(
+                f"Proxmox API {method} {path} TLS validation failed. Disable Validate SSL for self-signed certificates or install the CA certificate. Details: {exc}"
             ) from exc
         except requests.RequestException as exc:
             raise ProxmoxConnectionError(f"Proxmox API {method} {path} failed: {exc}") from exc