SSH Remote Terminal

SSH (Secure Shell Protocol) is an encrypted remote login protocol that allows users to securely access the Quectel Pi Debian system terminal (L1/M1) over the network from their computer. Through SSH, users can remotely execute commands, check service status, modify configuration files, and perform system debugging, making it suitable for development debugging, remote maintenance, and headless deployment scenarios.

💡 Prerequisites: The Quectel Pi development board (L1/M1) is connected to the same reachable network as the computer via Ethernet, Wi-Fi, or USB networking, and has an IP address assigned.

• Quectel Pi M1 device: The desktop environment is primarily GNOME, but also includes Weston. Access it via the Debug Uart serial console. For the M1 default login user, please use the account and password you created following the setup guide.

• Quectel Pi L1 device: The desktop environment is Weston. Enter the system via the Debug Uart serial console. The L1 default serial console login user is root with no password. You can also create a regular user such as q for login.

Preparation

1. Prepare a Quectel Pi development board (L1/M1) with the Debian system already started.

2. Ensure the development board and the computer are on the same reachable network.

3. Prepare a local debugging entry point for enabling or checking the SSH service for the first time:

   • Monitor and keyboard;

   • Debug Uart serial console;

   • Other already available local terminal entry points.

4. Prepare an SSH client on the computer:

   • Windows: QPiTerminal is recommended;

   • Linux: The ssh command is usually built-in;

   • macOS: The ssh command can be used directly in the terminal.

Software Installation

The Quectel Pi Debian system can use OpenSSH Server to provide SSH remote terminal service. After entering the development board via the serial console, execute the following command to check if it is already installed:

dpkg -l | grep -E "openssh-(server|client)"

If openssh-server is not installed, you can execute the following in the ADB Shell or serial console:

sudo apt update
sudo apt install -y openssh-server

Software Configuration

The main configuration file for the SSH service is /etc/ssh/sshd_config. Common configuration items are as follows:

Configuration Item	Description
Port	The listening port for the SSH service. The default port is 22.
PasswordAuthentication	Whether to allow password-based login. This item may appear commented out in the default configuration; the actual behavior depends on the OpenSSH defaults and system policy.
PermitRootLogin	Whether to allow root user login. It is recommended to log in as a regular user and use sudo as needed.
PubkeyAuthentication	Whether to allow public key authentication.

Check key configuration items via the serial console:

grep -nE "^(#)?(Port|PermitRootLogin|PasswordAuthentication|PubkeyAuthentication|AllowUsers|DenyUsers)" /etc/ssh/sshd_config

To modify the SSH port, edit the configuration file:

sudo vi /etc/ssh/sshd_config

After making changes, check the configuration syntax first, then restart the SSH service:

sudo sshd -t
sudo systemctl restart ssh

💡 Before modifying the port, firewall, or authentication method, ensure that you still have a recoverable entry point such as the serial console or local monitor to avoid being unable to log in remotely due to configuration errors.

Software Startup

Start the SSH service on the development board via the serial console:

sudo systemctl start ssh

Enable auto-start on boot:

sudo systemctl enable ssh

Check the service status:

systemctl is-active ssh
systemctl is-enabled ssh

If systemctl is-active ssh outputs active, the SSH service is running. If systemctl is-enabled ssh outputs enabled, the SSH service is set to auto-start on boot.

Remote Login

Get System IP Address

Execute the following command on the development board via the serial console to check the IP address:

hostname -I

In practice, use the IP address currently displayed by the development board.

Login Using QPiTerminal

On the Windows computer, open QPiTerminal, create a new SSH session, and configure it as follows:

Configuration Item	Configuration Value
Host	The actual IP address of the development board, e.g., 10.66.84.134
Port	22
User	The username on the development board system. The L1 default user is root, or a manually created regular user such as q; for the M1 default user, refer to the corresponding system image documentation, e.g., q.

After clicking Connect, enter the user’s password as prompted. Upon successful login, you can operate the Quectel Pi Debian terminal in QPiTerminal.

After successful login, you can execute the following commands to verify:

whoami
hostname
systemctl is-active ssh
hostname -I

Login Using a Specified Port

If the SSH port has been changed to a non-default port, e.g., 2222, the login command on the computer needs the -p parameter:

ssh -p 2222 <username>@<ip-address>

User Management

It is recommended to use a regular user for SSH login and use sudo when administrator privileges are needed. Check current user information:

id

Create a new user:

sudo adduser <username>

Add a user to the sudo group:

sudo usermod -aG sudo <username>

To disable SSH login for a specific user, use DenyUsers or AllowUsers in /etc/ssh/sshd_config to control which accounts can log in. For example, to allow only the q user to log in:

AllowUsers q

After making changes, execute:

sudo sshd -t
sudo systemctl restart ssh

Troubleshooting

Symptom	Troubleshooting Method
Connection timeout on the computer	Confirm that the development board and the computer are on the same reachable network; check if the IP address is correct; verify that the Ethernet cable, Wi-Fi, or USB network connection is normal.
Prompt Connection refused	Execute systemctl is-active ssh on the development board to confirm whether the SSH service is started.
Password error prompt	Confirm the username and password are correct; you can first log in to the system via the serial console and reset the user password.
Host key fingerprint confirmation prompt on first connection	Enter yes to continue the connection. If the fingerprint changes after reflashing the system, you can clean the old record for the corresponding IP in the known_hosts file on the computer.
Unable to log in after modifying configuration	Enter the system via the serial console or local monitor, execute sudo sshd -t to check the configuration syntax, then restore the correct configuration and restart the service.
sudo prompts hostname resolution failure	Check if the hostname in /etc/hostname matches the one in /etc/hosts. This prompt usually does not affect SSH service startup, but it is recommended to fix it.