Troubleshooting

This guide provides solutions to common issues with SPSA.

SPSA Diagnostic Commands

SPSA includes built-in tools for troubleshooting connectivity and configuration issues. Access these via the VM console as the spadmin user.

Test SSH Connectivity

sshping <hostname-or-ip>

Successful output:

Successfully connected to SSH at 192.168.20.5:22

Failed output:

Could not connect to 192.168.20.5:22

Test RDP Connectivity

rdpping <hostname-or-ip>

Successful output:

Successfully connected to RDP at 192.168.2.10:3389

Failed output:

Could not connect to 192.168.2.45:3389

Tests Must Pass

If these connectivity tests fail, SPSA cannot establish connections to the target systems. Diagnose and resolve network issues before proceeding.

Display IP Addresses

getip

Example output:

Interface: eth0   IP Address: 192.168.1.73
Interface: eth1   IP Address: 192.168.2.150

Change Keyboard Layout

sudo kbmap

Select from available layouts (Swiss-German, Swiss-French, Austrian, German).

SSH Access to SPSA

By default, SSH access to the SPSA appliance is disabled for security. Only enable it temporarily when needed.

Enable SSH Access

sudo sshon

Output:

SSH service started successfully.

Disable SSH Access

sudo sshoff

Output:

SSH service stopped successfully.

Security Warning

SSH access must be disabled when not in active use. A permanently enabled SSH server is a security risk for the SPSA appliance and all systems reachable through it.

Use cases for temporary SSH access:

  • Copying valid SSL certificates
  • Creating log files for support
  • Brief administrative access

Always run sudo sshoff when finished.

Connection Issues

Cannot Connect to Target System

Symptoms:

  • "Connection refused" error
  • Connection times out
  • Black screen

Diagnosis:

  1. Test connectivity from SPSA console: bash sshping <target-ip> # For SSH targets rdpping <target-ip> # For RDP targets

  2. If tests fail, check:

Cause Solution
Target offline Verify target system is running
Firewall blocking Check firewall rules on SPSA network and target
Wrong port Verify port number in connection settings
Network routing Check routing between SPSA and target
DNS resolution Test with IP address instead of hostname

RDP Black Screen

Causes:

  1. Windows loading slowly
  2. Display settings mismatch
  3. NLA authentication issue

Solutions:

Solution Details
Wait Windows may take 30+ seconds to load
Reduce color depth Try 16-bit instead of 32-bit
Check NLA Ensure NLA settings match target configuration
Verify credentials Check username format (DOMAIN\user or user@domain)

SSH Connection Refused

Check on target system:

# Verify SSH service is running
sudo systemctl status sshd

# Check if port 22 is listening
netstat -tlnp | grep 22

# Verify firewall allows SSH from SPSA IP
sudo iptables -L -n | grep 22

Check connection settings:

  • Username exists on target
  • Password authentication enabled (if using passwords)
  • SSH key format correct (if using keys)

VNC Authentication Failed

Common issues:

  • VNC password is different from user password
  • Wrong VNC port (5900 + display number)
  • VNC server not running

Verify on target:

# Check VNC service
ps aux | grep vnc

# Check listening port
netstat -tlnp | grep 590

Authentication Issues

Cannot Login to SPSA Portal

Checklist:

Check Action
Username Verify spelling (case-sensitive)
Password Check Caps Lock is off
Account status May be disabled or expired
MFA code Ensure authenticator time is synchronized
Browser Try Chrome or Edge

MFA Code Not Working

Causes:

  • Phone/authenticator time out of sync
  • Wrong account in authenticator
  • Expired code (codes valid for 30 seconds)

Solutions:

  1. Verify phone time is auto-synchronized
  2. Confirm correct SPSA account in authenticator
  3. Wait for next code cycle

Wrong Credentials for Target

Remember:

  • SPSA Portal credentials ≠ Target system credentials
  • Verify target system username/password separately
  • Check domain format: DOMAIN\username or user@domain

Web Interface Issues

Cannot Access SPSA Portal

Issue Solution
Connection refused Verify SPSA appliance is running
Timeout Check network connectivity to SPSA IP
Certificate error Accept self-signed cert or install trusted cert
Page not loading Try different browser (Chrome/Edge recommended)

Portal Not Responding

  1. Check appliance status via VM console
  2. Verify services are running
  3. Check disk space and memory
  4. Contact support if issue persists

Slow Performance

Browser-side:

  • Use recommended browser (Chrome/Edge)
  • Clear browser cache
  • Disable browser extensions

Connection-side:

  • Reduce color depth (16-bit)
  • Disable desktop effects on target
  • Check network bandwidth

Session Issues

Session Disconnects Unexpectedly

Cause Solution
Network interruption Check network stability
Idle timeout Reconnect, check timeout settings
Target reboot Wait for target to come back online
SPSA overload Check appliance resources

Clipboard Not Working

Check:

  1. Clipboard may be disabled in connection settings
  2. Only text content is supported (not files/images)
  3. Use Ctrl+Alt+Shift menu for clipboard panel

Access clipboard:

  1. Press Ctrl+Alt+Shift during session
  2. Use clipboard panel to transfer text
  3. Check connection settings for clipboard restrictions

Keyboard Issues in Session

Issue Solution
Wrong characters Check keyboard layout in connection settings
Special keys not working Use Ctrl+Alt+Shift menu for on-screen keyboard
Modifier keys stuck Click outside session window and back

Common Error Messages

Error Meaning Solution
Connection refused Target not accepting connections Check target service is running
Connection timed out Network timeout Check network path with sshping/rdpping
Authentication failed Wrong credentials Verify username/password for target
Permission denied Access denied Check user permissions for connection
Server certificate error SSL/TLS issue Enable "Ignore server certificate" for self-signed
NLA required Target requires NLA Set Security mode to NLA

Network Troubleshooting

From SPSA Console

# Display current IP configuration
getip

# Test connectivity to target
sshping 192.168.1.50
rdpping 192.168.1.50

# Test DNS resolution (if DNS tools available)
nslookup hostname.domain.com

Firewall Checklist

Inbound to SPSA:

  • [ ] TCP 443 open from user networks
  • [ ] TCP 80 open from internet (if using Let's Encrypt)

Outbound from SPSA:

  • [ ] TCP 3389 to Windows targets (RDP)
  • [ ] TCP 22 to Linux targets (SSH)
  • [ ] TCP 5900-5910 to VNC targets
  • [ ] TCP 23 to Telnet targets (if needed)
  • [ ] UDP 53 to DNS servers
  • [ ] UDP 123 to NTP servers
  • [ ] TCP 80/443 to internet (for appliance updates)

Common Network Issues

Symptom Likely Cause
Portal accessible, connections fail SPSA → Target firewall blocking
Portal not accessible User → SPSA firewall blocking
Intermittent disconnects Network instability, packet loss
Slow connections Bandwidth limitation, latency

Log Collection for Support

When contacting support, collect:

  1. SPSA version (visible in portal footer)
  2. Description of the issue
  3. Steps to reproduce
  4. Error messages (screenshots helpful)
  5. Connectivity test results (sshping/rdpping output)

Enable SSH for Log Access

# Enable SSH temporarily
sudo sshon

# After collecting logs via SCP/SFTP
sudo sshoff

Getting Help

Contact Support
Email support@skill-plan.com
Website https://www.skill-plan.com

Information to Provide

  1. SPSA edition (Foundation/Pro)
  2. Guacamole version (shown in portal)
  3. Hypervisor platform (ESXi/Hyper-V)
  4. Network configuration
  5. Detailed error description
  6. Steps to reproduce the issue
  7. Screenshots if applicable