Access instances without a public IP address using Session Manager CLI port forwarding - Elastic Compute Service

Session Manager CLI (ali-instance-cli) enables TCP port forwarding over Cloud Assistant and WebSockets to access private-IP instance services or tunnel through a jump server.

Use cases

Use case 1: Access services on a private-IP instance.

Map a service port on an instance without a public IP address (such as port 80 for Nginx, 22 for SSH, 3389 for RDP, or 3306 for MySQL) to a local port, then connect locally to access the remote service.

Use case 2: Use an instance as a jump server to reach other private hosts.

For services you cannot reach directly, such as an ApsaraDB RDS for MySQL database, use an ECS instance with network access to the target as a jump server. The port forwarding session tunnels through this instance to the private services.

Important

A port forwarding session stays active only while the command-line window is open. Closing the window terminates the session.

Access services on a private-IP instance

Complete the preparations and install and configure the Session Manager CLI, then follow these steps.

On Windows

In PowerShell, navigate to the ali-instance-cli.exe directory and run:

# Replace INSTANCE_ID with the ID of the instance for which you want to set up port forwarding, TARGET_PORT with the port of the target ECS instance, and LOCAL_PORT with the port to map on your local machine.
.\ali-instance-cli.exe portforward -i INSTANCE_ID -r TARGET_PORT -l LOCAL_PORT

When Waiting for connections appears, the tunnel is active. Access the instance's TARGET_PORT through 127.0.0.1:<local_port>.

Example: forward Nginx port 80 on instance i-bp1****** to local port 8080: .\ali-instance-cli.exe portforward -i i-bp1****** -r 80 -l 8080.

On macOS or Linux

In the terminal, navigate to the ali-instance-cli directory and run:

#Replace INSTANCE_ID with the ID of the instance for which you want to set up port forwarding, TARGET_PORT with the port of the target ECS instance, and LOCAL_PORT with the port to map on your local machine.
./ali-instance-cli portforward -i INSTANCE_ID -r TARGET_PORT -l LOCAL_PORT

When Waiting for connections appears, the tunnel is active. Access the instance's TARGET_PORT through 127.0.0.1:<local_port>.

Example: forward Nginx port 80 on instance i-bp1****** to local port 8080: ./ali-instance-cli portforward -i i-bp1****** -r 80 -l 8080.

Use an instance as a jump server

Complete the preparations and install and configure the Session Manager CLI, then follow these steps.

On Windows

In PowerShell, navigate to the ali-instance-cli.exe directory and run:

# Replace INSTANCE_ID with the ID of the jump server instance, TARGET_IP with the IP address of the target host, TARGET_PORT with the port of the target host, and LOCAL_PORT with the port to map on your local machine.
.\ali-instance-cli.exe portforward -i INSTANCE_ID -r TARGET_IP:TARGET_PORT -l LOCAL_PORT

When Waiting for connections appears, the jump server tunnel is established. Traffic to 127.0.0.1:<local_port> routes through the jump server to TARGET_IP:TARGET_PORT.

Example: route traffic to an RDS for MySQL instance at rm-******.mysql.rds.aliyuncs.com:3306 through jump server i-bp1****** to local port 13306: .\ali-instance-cli.exe portforward -i i-bp1****** -r rm-******.mysql.rds.aliyuncs.com:3306 -l 13306.

On macOS or Linux

In the terminal, navigate to the ali-instance-cli directory and run:

#Replace INSTANCE_ID with the ID of the jump server instance, TARGET_IP with the IP address of the target host, TARGET_PORT with the port of the target host, and LOCAL_PORT with the port to map on your local machine.
./ali-instance-cli portforward -i INSTANCE_ID -r TARGET_IP:TARGET_PORT -l LOCAL_PORT

When Waiting for connections appears, the jump server tunnel is established. Traffic to 127.0.0.1:<local_port> routes through the jump server to TARGET_IP:TARGET_PORT.

Example: map an RDS for MySQL instance (rm-******.mysql.rds.aliyuncs.com:3306) to local port 13306 through jump server i-bp1******: ./ali-instance-cli portforward -i i-bp1****** -r rm-******.mysql.rds.aliyuncs.com:3306 -l 13306.

FAQ

CLI hangs: Instance not running

If the command line hangs after you run an ali-instance-cli command, the target instance may not be in the Running state. To check the instance status, see Check that the instance is in the Running state.

CLI hangs: Security group issue

If the command line hangs after you run an ali-instance-cli command, the instance's security group rules may be blocking the required outbound ports. By default, a basic security group allows all outbound traffic. This issue can occur if you have modified the outbound rules or if you are using an advanced security group.

When you use Session Manager to connect to an ECS instance, make sure that Cloud Assistant Agent running on the ECS instance is connected to the Cloud Assistant server by adding the following rules to an outbound security group:

Compared with connection methods, such as SSH and Remote Desktop Protocol (RDP), Cloud Assistant Agent actively establishes a WebSocket connection to the Session Manager server. You need to only open the outbound WebSocket port of the Cloud Assistant server in a security rule. For information about how Session Manager works, see the How Session Manager works section of this topic.

Important

If you use basic security groups including the default security group, all outbound traffic is allowed. No additional configuration is required.
If you use an advanced security group, all outbound traffic is denied. You must configure the relevant rules. The following table describes the rules. For information about security groups, see Basic and advanced security groups.

For information about how to add rules to a security group, see Add a security group rule.

Action	Priority	Protocol type	Port range	Authorization object	Description
Allow	1	Custom TCP	443	`100.100.0.0/16`	This port is used to access the Cloud Assistant server.
Allow	1	Custom TCP	443	`100.0.0.0/8`	This port is used to access the server on which the Cloud Assistant Agent installation package is stored when you want to install or update Cloud Assistant Agent.
Allow	1	Custom UDP	53	`0.0.0.0/0`	This port is used to resolve domain names.

If you want to connect to an instance by using only Session Manager, delete the inbound rules that allow the SSH port (default 22) and RDP port (default 3389) from a security group to improve the security of the ECS instance.

DeliveryTimeout error: Cloud Assistant Agent is offline

A DeliveryTimeout error indicates Cloud Assistant Agent may be offline. To check the agent status, see Check whether the Cloud Assistant Agent is installed on an instance.

Command execution error: Session Manager is disabled, please enable first

If the session manager is disabled, please enable first error occurs when you run the ali-instance-cli command, it indicates that the Session Manager feature is disabled. Enable the feature in the console. For more information, see Enable the Session Manager service.

Analyzing ali-instance-cli logs

If you encounter issues with Session Manager CLI, analyzing the logs can help diagnose the problem.

View logs for the Session Manager CLI: When you use the Session Manager CLI (ali-instance-cli), a log directory is generated in the directory where the tool is located. You can navigate to this directory to view the log files, such as ~/log/aliyun_ecs_session_log.2022XXXX.

Cloud Assistant Agent logs:

Linux

/usr/local/share/aliyun-assist/<agent_version>/log/

Windows

C:\ProgramData\aliyun\assist\<agent_version>\log