FAQ

SSH Login Troubleshooting Checklist

  1. System Confirmation: Ensure your target server runs a Linux operating system (Windows or macOS host connections are not currently supported).
  2. Three-Factor Check: Carefully verify the server's public IP, SSH port (default 22), and username/password.
  3. Permission Requirements: It is recommended to use root or an account with sudo privileges.
  4. Network Reachability (Web Online Edition):
    • Confirm the server has a public IP.
    • Confirm the server firewall has not blocked overseas traffic (GMSSH online edition nodes are located in Singapore).
    • Confirm the SSH port is allowed in the cloud platform security group.
Error / SymptomPossible CauseQuick Solution
Process exited with status 1Unsupported architecture/bit width1. Check bit width: GMSSH does not support 32-bit OS. Ensure it is 64-bit.
2. Check architecture: Confirm the downloaded version matches the CPU architecture (e.g., don't use an ARM package on x86).
3. Run uname -m to check architecture, getconf LONG_BIT to check bit width.
ssh: subsystem request failedSFTP service not enabled1. GMSSH visual file management depends on the SFTP subsystem.
2. Check /etc/ssh/sshd_config and ensure the following line exists and is not commented out:
Subsystem sftp /usr/lib/openssh/sftp-server
3. After modification, run sudo systemctl restart ssh.
Connection Refused1. SSH service not running
2. Wrong port number		1. Run sudo systemctl status ssh to confirm the service is running.
2. Check if the SSH port is the default 22.
Connection Timeout1. Firewall/security group not configured
2. Network unreachable		1. Cloud server users: Allow TCP 22 in your cloud platform security group.
2. Local firewall: Run sudo ufw allow 22/tcp or equivalent.
Username or password is incorrect1. Wrong credentials
2. Root login disabled		1. Double-check username and password.
2. Check if /etc/ssh/sshd_config has PermitRootLogin yes.

Desktop Client FAQ

Q1: Security software (e.g., 360) flags the client as a risk. What should I do?

A: This is a heuristic false positive from the security software. You can safely choose "Allow" or "Add to trusted list".

We understand the importance of security for operations tools, so GMSSH has taken the following measures:

  1. Microsoft Official Code Signing: The GMSSH client integrates a Microsoft-certified code signing certificate, ensuring the software's origin is traceable and untampered.
  2. Rigorous Virus Scanning: Every release is scanned by top-tier antivirus engines like Kaspersky before distribution.
  3. Why the false positive: GMSSH includes batch script dispatch, SSH tunnel communication, and other low-level network operations that may trigger alerts from some security software (e.g., 360) on first scan.

💡 Recommended Actions:

  • Select "Allow all operations" or "Don't remind again" when prompted.
  • Add the GMSSH installation directory to 360's "Trusted Zone/Whitelist".

Q2: Error AxiosError: Network Error when adding a server?

A: This is usually caused by Windows Firewall blocking the client's network access.

  • Troubleshooting: Windows Firewall may restrict newly installed programs from accessing the network.
  • Solution:
    1. Go to Control Panel > System and Security > Windows Defender Firewall.
    2. Click "Allow an app through Windows Firewall".
    3. Find GMSSH in the list and ensure both "Private" and "Public" are checked.
    4. If GMSSH is not listed, click "Allow another app" and manually add the GMSSH executable.

Q3: Local service page stuck on Loading screen, UI won't load?

A: This is usually caused by incorrect MIME type settings in Windows Registry, causing the browser to refuse loading JS/CSS files.

  • Root Cause: Modern browsers require accurate Content-Type for scripts and styles. If your system registry returns .js as text/plain or .css as a non-standard format, the browser will block loading.

  • Check: Ensure the registry returns:

    • JS files: text/javascript; charset=utf-8
    • CSS files: text/css; charset=utf-8

  • Manual Fix:

    1. Press Win + R, type regedit to open Registry Editor.
    2. Navigate to: HKEY_CLASSES_ROOT\.js, confirm Content Type is text/javascript.
    3. Navigate to: HKEY_CLASSES_ROOT\.css, confirm Content Type is text/css.
#### 🛠️ One-Click Fix Script (save as fix_mime.reg and run)
```regedit
Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\.js]
"Content Type"="text/javascript"

[HKEY_CLASSES_ROOT\.css]
"Content Type"="text/css"

Q5: Terminal (black window) connects, but desktop layout/file manager won't open?

A: This is usually related to system compatibility or account permissions. Please check in order:

  • System Architecture: Confirm your server is a 64-bit Linux system. GMSSH's graphical management components do not support 32-bit OS or kernels older than 3.10.
  • High-Privilege Account: If managing NAS (e.g., Synology, QNAP), restricted cloud environments, or embedded devices, use root or admin accounts.
    • Reason: Non-admin accounts cannot start the backend processes required for the graphical interface due to permission isolation.
  • SFTP Status: Refer to the SSH troubleshooting section above to check if SFTP subsystem is enabled.

Q6: Connection failed — how to determine if it's a GMSSH issue or a network issue?

A: The simplest way is to use your system's built-in SSH command for a "control experiment".

  • Verification Steps:

    1. Open a terminal on your computer (Windows: CMD/PowerShell, Mac: Terminal).
    2. Run: ssh -p [port] [username]@[server-IP].

  • Interpretation:

    • If the SSH command also fails: The issue is your server IP, firewall settings, credentials, or network connectivity (e.g., internal network cannot reach public IP). Resolve the network issue first — this is outside GMSSH's scope.
    • If SSH works but GMSSH doesn't: Check if Windows Firewall is blocking GMSSH (see Q2), or contact our technical support.

Self-Hosted Deployment FAQ

Q1: Cannot access Web UI after Docker deployment?

A: Please troubleshoot step by step:

  1. Check Container Status: Run docker ps to confirm the gm-service container is running (Up).

  2. Check Port Mapping:

    • Confirm the host firewall allows the mapped TCP port.
    • Confirm Docker mapping is correct: the PORTS column should show 0.0.0.0:<mapped-port>->80/tcp.

  3. Check Container Logs: Run docker logs gm-service to check for error messages.

Q2: Cannot access after Shell script deployment?

A: Please troubleshoot step by step:

  1. Check Port Usage: Run netstat -tulnp | grep :80 to confirm port 80 is not occupied by other programs.

  2. Check Service Status: Run ps aux | grep gm to confirm the GMSSH process is running.

  3. Check Firewall: Run sudo ufw status or sudo firewall-cmd --list-all to ensure port 80 is allowed.

Q3: How to change the mapped port?

A1: Docker deployment:

  1. Stop Container: Run docker stop gm-service.

  2. Remove Container: Run docker rm gm-service.

  3. Recreate Container: Run the following command to change the port mapping to 8091:

    docker run -d --name gm-service -p 8091:80 --restart always gm-service:latest

A2: Shell script deployment:

  1. Navigate to the deploy script directory: Run ./deploy.sh setport [port] to complete the change.

How to Get Technical Support?

  • Visit the official website for the latest information
  • Submit an Issue to the GitHub repository
  • Join the community discussion group
Last Updated:
Contributors: guanxi, xiarui