Scanner Appliance Troubleshooting
Following are the commonly faced issues and their troubleshooting solutions:
How to Manage Virtual Scanner Instances?
To manage instances effectively, ensure the following:
-
Allowable Instance Size
The maximum supported size for a scanner instance was 16 CPUs and 16 GB RAM. From the qVSA-3.10 release, these limitations have been removed.
-
Instance Snapshots/Cloning Not Allowed
Using a snapshot or clone of a virtual scanner instance to create a new instance is strictly prohibited. The new instance will not function as a scanner. All configuration settings and platform registration information will be lost. This could also lead to scans failing and errors for the original scanner.
-
Moving/Exporting Instance Not Allowed
Moving or exporting a registered scanner instance from a virtualization platform (HyperV, VMware, XenServer) in any file format to a cloud platform (AWS, Azure, GCE, OpenStack) is strictly prohibited. This will break scanner functionality and permanently lose all of its settings.
-
Scanner Deployment Failure
Ensure that UEFI, Secure Boot or similar options are unchecked or removed during Scanner VM deployment. These options are not supported by QVSA.
If Generation 1 or equivalent standard settings are available, then make the selection based on the virtualization platform.
What to Do? If You See Communication Failure Message
The COMMUNICATION FAILURE message appears if there is a network breakdown between the scanner and the Qualys Cloud Platform.
The communication failure may be due to one of these reasons:
- The local network goes down,
- Internet connectivity is lost for some reason.
- Any of the network devices between the scanner and the Qualys Cloud Platform goes down.
Sequence of Events of Network Breakdown
Following is the sequence of events of network breakdown:
- If there are no scans and/or maps running on the appliance: The next time the scanner sends a polling request to the Qualys Cloud Platform, the polling request fails, and then the COMMUNICATION FAILURE message appears.
- If scans and/or maps are running on the appliance: The COMMUNICATION FAILURE message appears after the running scans and/or maps time out.
In this case, it is recommended to cancel any running scans and/or maps and restart them to ensure that the results are accurate.
After the network breakdown is resolved, you can see the scanner-friendly name and IP address, and you can start new scans.
The COMMUNICATION FAILURE message remains until the next time the scanner makes a successful polling request to the Qualys Cloud Platform. There may be a lag time after the network is restored and before the scanner is back online, depending on when the subsequent polling request is scheduled. Additional time is necessary for communications to be processed by a Proxy server if the scanner has a Proxy configuration.
How to Resolve Network Errors?
An appliance network error indicates the Scanner attempted to connect to the Qualys Cloud Platform and failed.
The Scanner is not functional until the error is resolved.
LAN / WAN Errors
The following are LAN / WAN Errors along with their solutions:
Physical Scanner Appliance Error |
Virtual / Cloud / Consultant Scanner Appliance Error |
Solution |
---|---|---|
no CARRIER on the LAN interface |
The LAN network cable/port may be disconnected. |
This error appears when attempting to configure a proxy or personalization while the LAN network cable or port is disconnected. Check that the LAN port is connected. |
no CARRIER on the WAN interface |
The WAN network cable/port may be disconnected. |
This error appears when attempting to configure a proxy or personalization while the WAN network cable or port is disconnected. Check that the WAN port is connected. |
LAN has no IPv4 address |
The LAN interface is unable to obtain a valid IPv4 address. |
Ensure the LAN cable or port is connected correctly. If you are configuring the LAN for DHCP IP assignment, verify that the DHCP server is reachable and functioning correctly. |
WAN has no IPv4 address |
The WAN interface is unable to obtain a valid IPv4 address. |
Ensure the WAN cable or port is connected correctly. If you are configuring the WAN for DHCP IP assignment, verify that the DHCP server is reachable and functioning correctly. |
LAN has no DNS servers |
LAN has no DNS servers configured |
Check that the LAN interface has valid DNS servers configured. |
WAN has no DNS servers |
WAN has no DNS servers configured |
Check that the WAN interface has valid DNS servers configured. |
LAN DNS can't resolve QG URL |
LAN DNS servers cannot resolve the QG URL=['<PlatformURL>] |
Ensure the LAN’s configured DNS servers can resolve the Qualys Platform URL. See https://www.qualys.com/platform-identification/ for platform URLs. |
WAN DNS can't resolve QG URL |
WAN DNS servers cannot resolve the QG URL=['<PlatformURL>] |
Ensure the WAN’s configured DNS servers can resolve the Qualys Platform URL. See https://www.qualys.com/platform-identification/ for platform URLs. |
Invalid LAN IP configuration |
Invalid or unusable IP in LAN configuration |
Ensure a valid IP address is assigned to the LAN interface. |
Invalid WAN IP configuration |
Invalid or unusable IP in WAN configuration |
Ensure a valid IP address is assigned to the WAN interface. |
LAN DNS can't resolve proxy |
LAN DNS servers cannot resolve proxy FQDN=<ProxyFQDN> |
Ensure LAN DNS server(s) can resolve the scanner’s configured proxy hostname. |
WAN DNS can't resolve proxy |
WAN DNS servers cannot resolve proxy FQDN=<ProxyFQDN> |
Ensure WAN DNS server(s) can resolve the scanner’s configured proxy hostname. |
N/A |
Different types/models of Network adapters are configured. Qualys advises against doing that. |
For VMware-based scanners, select the same network adapter type for LAN and WAN interfaces, for example, vmxnet3 for LAN and WAN network adapters. |
LAN DHCP lease has no gateway |
LAN DHCP lease has no valid gateway |
Ensure the DHCP server is assigning a valid gateway for the LAN interface. |
WAN DHCP lease has no gateway |
WAN DHCP lease has no valid gateway |
Ensure the DHCP server is assigning a valid gateway for the WAN interface. |
Duplicate LAN and WAN config |
LAN and WAN are on the same network [<IPaddress>] |
Ensure the LAN interface has network connectivity to its configured DNS servers. |
LAN DNS server not reachable |
LAN DNS servers [<DNS1>, <DNS2>] not reachable |
Ensure the LAN interface has network connectivity to its configured DNS servers. |
WAN DNS server not reachable |
WAN DNS servers [<DNS1>, <DNS2>] not reachable |
Ensure the WAN interface has network connectivity to its configured DNS servers. |
LAN and WAN same gateway |
LAN and WAN have the same gateway address [<GatewayIP>] |
LAN and WAN must be configured with different subnets and gateway addresses. |
Duplicate IP detected |
Another host already uses the same address on LAN/WAN |
Ensure LAN/WAN is configured with an IP address not already in use by another host on the network. |
Proxy Errors
The following are proxy Errors along with their solutions:
Physical Scanner Appliance Error |
Virtual / Cloud / Consultant Scanner Appliance Error |
Solution |
---|---|---|
Invalid proxy IP |
Invalid or unusable proxy IP=<IPaddress> |
Ensure proxy configuration on the scanner is configured with a valid IP address for the proxy. |
Invalid proxy auth config |
Empty username configured for proxy authentication. |
Ensure the proxy configuration on the scanner is configured with a valid proxy username and password. |
unexpected proxy HTTP/403 |
Error: Connection with local proxy was interrupted while receiving data: curl_code=56 err=[Received HTTP code 403 from proxy after CONNECT] url=<PlatformURL>/msp/iscan_init_time.php via_proxy=<ProxyIP>:<ProxyPort> connect_code=403 local_ip=<ScannerIP>:38250 iface=eth0 remote_ip=<ProxyIP>:<ProxyPort> |
Ensure the configured proxy user on the scanner has authorization to connect to the Qualys Platform. See https://www.qualys.com/platform-identification/ for platform URLs. |
unexpected proxy HTTP/407 |
Error: Connection with local proxy was interrupted while receiving data: curl_code=56 err=[Received HTTP code 407 from proxy after CONNECT] url=<PlatformURL>/msp/iscan_init_time.php via_proxy=<ProxyIP>:<ProxyPort> connect_code=407 local_ip=<ScannerIP>:38248 iface=eth0 remote_ip=<ProxyIP>:<ProxyPort> |
Ensure the scanner is configured with a valid proxy username and password. See https://www.qualys.com/platform-identification/ for platform URLs. |
unexpected proxy HTTP/503 |
Error: Connection with local proxy was interrupted while receiving data: curl_code=56 err=[Received HTTP code 503 from proxy after CONNECT] url=<PlatformURL>/msp/iscan_init_time.php via_proxy=<ProxyIP>:<ProxyPort> connect_code=503 local_ip=<ScannerIP>:38252 iface=eth0 remote_ip=<ProxyIP>:<ProxyPort> |
Ensure the proxy server can connect to the Qualys Platform. See https://www.qualys.com/platform-identification/ for platform URLs. |
Personalization Code Errors
The following are Personalization Code Errors along with their solutions:
Physical Scanner Appliance Error |
Virtual / Cloud / Consultant Scanner Appliance Error |
Solution |
---|---|---|
N/A |
Invalid personalization code [<PersCode>] entered - please retry. |
Provide a valid personalization code for scanner activation. |
N/A |
Personalization code [<PersCode>] was rejected by Qualys - most likely, the code is already in use. |
Retry scanner activation with a valid and unused personalization code. |
Qualys Platform Connectivity Errors
The following are Qualys Platform Connectivity Errors along with their solutions:
Physical Scanner Appliance Error |
Virtual / Cloud / Consultant Scanner Appliance Error |
Solution |
---|---|---|
Error connect to server (07) |
With Proxy Configuration: |
With Proxy Configuration: |
Timeout was reached (28) |
With Proxy Configuration: |
With Proxy Configuration: |
Failed sending peer data (55) |
With Proxy Configuration: |
With Proxy Configuration: |
Fail receiving peer data (56) |
With Proxy Configuration: |
With Proxy Configuration: |
SSL peer cert was not OK |
Error: curl_code=60 err=[SSL certificate problem: error number 1] url=<PlatformURL>/msp/iscan_bind.php via_proxy=<ProxyIP>:<ProxyPort> connect_code=200 local_ip=<ScannerIP>:35320 iface=eth0 remote_ip=<ProxyIP>:<ProxyPort> |
This issue may occur when a proxy or intercepting device interferes with the certificate exchange process between the scanner and Qualys Platform. Contact Qualys Support. See https://www.qualys.com/platform-identification/ for platform URLs. |
Unexpected QG HTTP/401 |
Error: Unexpected Qualys HTTP/401 - please contact customer support. |
Report this error to Qualys Support and include all configuration details. |
Unexpected QG HTTP/500 |
Error: Unexpected Qualys HTTP/500 - please contact customer support. |
Report this error to Qualys Support and include all configuration details. |
This scan_id does not exist |
This Scanner is not registered on the Qualys Platform. |
The scanner is not registered with Qualys. Contact Qualys Support. |
This Scanner is disabled |
This Scanner has been disabled in your Qualys account. |
Report this error to Qualys Support. |
Account expired |
The Qualys subscription for this Scanner has expired. |
Report this error to Qualys Support. |
SSL connect error (35) |
SSL connect error (35) |
Curl error code 35 means that SSL negotiation has failed due to incompatible cryptographic protocols between your network, VIP or intermediate devices, and the Qualys platform. Ensure your network, VIP, or intermediate devices do not interfere with TLS traffic between Scanner Appliances and Qualys Platform endpoints. |
Filesystem Mount Errors
The following are Filesystem Mount Errors along with their solutions:
Physical Scanner Appliance Error |
Virtual / Cloud / Consultant Scanner Appliance Error |
Solution |
---|---|---|
EFS fsck fatal errors |
e2fsck error - please contact customer support. |
Report this error to Qualys Support. |
EFS mount fatal error |
mount error - please contact customer support. |
Report this error to Qualys Support. |
How to Resolve Network Errors for Older Appliance Models?
A network error is an appliance configuration error indicating that the scanner appliance attempted to connect to the Qualys Cloud Platform but failed.
The Scanner Appliance is not functional until the error is resolved.
If you are using older appliance model, there might be different types of errors. Refer to the description provided in the table to help you resolve the issue. If you still need help, identify the error code when you contact Qualys Support.
Error Code |
Description |
---|---|
E00, E01 |
Internal error (NTLM Proxy error) |
E02 |
Internal error (Proxy error) |
E03 |
Proxy configuration error |
E04 |
No connectivity after the Proxy was disabled |
E05 |
DNS lookup of the Qualys server failed (maybe network connectivity problem) |
E06 |
Cannot reach the Qualys server via HTTPS |
E07 |
Invalid LAN IP address or LAN gateway address |
E08 |
Invalid WAN IP address or WAN gateway address |
E09 |
LAN IP address or LAN gateway address cannot be 127.0.0.1 |
E10 |
Could not configure the LAN interface |
E11 |
WAN IP address or WAN gateway address cannot be 127.0.0.1 |
E12 |
Could not configure the WAN interface |
E13 |
DNS lookup of the Qualys server failed due to a network connectivity problem |
E14 |
DNS lookup of the Qualys server failed during scanner activation due to a network connectivity problem |
More general error codes may be overwritten by more specific ones.
For example, the scanner may return the error code E04 (No connectivity after the Proxy was disabled). After trying to connect for a while, the error code may be overwritten by E13 (DNS lookup of the Qualys Cloud Platform server failed). When troubleshooting the network error, it's useful to watch these error codes scroll by.
You might want to check out our Quick Start Guide (prior version) https://www.qualys.com/docs/qualys-scanner-appliance-quick-start-guide-3120-a1.pdf
Proxy Support for Scanner Appliances
The scanner appliance includes Proxy support with or without authentication - Basic or NTLM. The Proxy server must be assigned a static IP address and must allow transparent SSL tunneling. Proxy level termination (as implemented in SSL bridging, for example) is not supported. The appliance does not support Proxy servers in networking environments where the Proxy server IP address is dynamically assigned. The appliance does not support SOCKS proxies.
While using a scanner appliance with a Proxy configuration, you may notice the following:
- Lag Time for configuration changes to take effect. Changes may take effect after a period of time that is significantly longer than the polling interval. This is because there is additional time necessary for communications to be processed by the Proxy server.
- No results or incomplete results. If the Proxy server sets limits for the absolute session timeout and/or the amount of outbound data that can be sent from the scanner, you may receive no results or incomplete results. It's possible that your scans will terminate if these limits are set and a large number of IPs are scanned.
How to Configure Split Network?
By default, the scanner appliance LAN interface services all traffic to the Qualys Cloud Platform. This includes management traffic (software updates, health checks, scan data uploads) and scanning traffic.
You can set up a split network configuration for your appliance by configuring the WAN interface through the scanner appliance console. This allows scanner appliances in networks without direct Internet access or access via an SSL proxy.
Once configured, management traffic will be routed through the WAN interface while scanning traffic will go through the LAN interface. No internal traffic will be routed or bridged to the WAN interface, and no management traffic will be routed or bridged to the LAN interface.
Do I need to configure Network Time Protocol (NTP)?
No, this is not necessary. The Scanner Appliance automatically syncs the time from the Qualys SOC (Security Operations Center) for your account or location. So, there is nothing you need to configure for NTP.
Tell me About Virtual Scanner Sizing and Capacity
Refer to the following articles to learn about sizing and capacity for virtual scanners.
Virtual Scanner Appliance Sizing