Access instances without a public IP via port forwarding-Elastic Compute Service(ECS)-阿里云帮助中心

The Session Manager CLI (ali-instance-cli) uses Cloud Assistant and WebSocket for TCP port forwarding, allowing you to directly access services on an instance without a public IP and use the instance as a jump server to access other private network services.

Use cases

Use case 1: Access services on an ECS instance without a public IP.

Map a service port (such as 80 for Nginx, 22 for SSH, 3389 for RDP, or 3306 for MySQL) from an ECS instance without a public IP to a port on your local machine. You can then access the service on the instance by connecting to the local port.

Use case 2: Use an instance as a jump server to access services on other private hosts.

For private services that do not support direct port forwarding, such as an RDS for MySQL database, you must use an ECS instance with network access to the target service as a jump server. The jump server then routes traffic to the private service.

Important

A port forwarding session is active only while the command-line window is running. Keep this window open to maintain the connection. Closing the window immediately terminates the session.

Scenario 1: Access services on a private instance

Before you begin, make sure that you have completed the prerequisites and installed and configured the Session Manager CLI.

On Windows

In PowerShell, go to the directory where ali-instance-cli.exe is located and run the following command.

# Replace INSTANCE_ID with the ID of your target instance, TARGET_PORT with the service port on the target ECS instance, and LOCAL_PORT with the port on your local machine.
.\ali-instance-cli.exe portforward -i INSTANCE_ID -r TARGET_PORT -l LOCAL_PORT

The output Waiting for connections indicates that the port forwarding connection is established. Connecting to 127.0.0.1:<local_port> on your computer now accesses the service on the instance's <target_port>.

Example: To forward the default Nginx port 80 on the target ECS instance i-bp1****** to local port 8080, run .\ali-instance-cli.exe portforward -i i-bp1****** -r 80 -l 8080.

On macOS or Linux

In the terminal, go to the directory where ali-instance-cli is located and run the following command.

# Replace INSTANCE_ID with the ID of your target instance, TARGET_PORT with the service port on the target ECS instance, and LOCAL_PORT with the port on your local machine.
./ali-instance-cli portforward -i INSTANCE_ID -r TARGET_PORT -l LOCAL_PORT

Example: To forward the default Nginx port 80 on the target ECS instance i-bp1****** to local port 8080, run ./ali-instance-cli portforward -i i-bp1****** -r 80 -l 8080.

Scenario 2: Use an instance as a jump server

Before you begin, make sure that you have completed the prerequisites and installed and configured the Session Manager CLI.

On Windows

In PowerShell, go to the directory where ali-instance-cli.exe is located and run the following command:

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

The output Waiting for connections indicates that the jump server channel is established. Traffic sent to 127.0.0.1:<local_port> is now forwarded through the jump server to <target_ip>:<target_port>.

Example: To map an RDS for MySQL instance with the private endpoint rm-******.mysql.rds.aliyuncs.com:3306 to local port 13306 through the ECS instance i-bp1****** as a jump server, run the following command: .\ali-instance-cli.exe portforward -i i-bp1****** -r rm-******.mysql.rds.aliyuncs.com:3306 -l 13306

On macOS or Linux

In the terminal, go to the directory where ali-instance-cli is located and run the following command.

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

Example: To map an ApsaraDB RDS for MySQL instance (private endpoint rm-******.mysql.rds.aliyuncs.com:3306) to local port 13306 through the ECS instance i-bp1****** as a jump server, run the following command: ./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.

Running a command results in a DeliveryTimeout prompt (The Cloud Assistant Agent is offline)

If a DeliveryTimeout message appears when you run the ali-instance-cli command, the Cloud Assistant Agent may be offline. To check the status of the Cloud Assistant Agent, see Check whether the Cloud Assistant Agent is installed.

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