Forward ports to instances without public IP addresses
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  | 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.  |
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_PORTWhen Waiting for connections appears, the tunnel is active. Access the instance's TARGET_PORT through 127.0.0.1:<local_port>.
Example: forward Nginx port80on instancei-bp1******to local port8080:.\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_PORTWhen Waiting for connections appears, the tunnel is active. Access the instance's TARGET_PORT through 127.0.0.1:<local_port>.
Example: forward Nginx port80on instancei-bp1******to local port8080:./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_PORTWhen 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 atrm-******.mysql.rds.aliyuncs.com:3306through jump serveri-bp1******to local port13306:.\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_PORTWhen 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 port13306through jump serveri-bp1******:./ali-instance-cli portforward -i i-bp1****** -r rm-******.mysql.rds.aliyuncs.com:3306 -l 13306.
FAQ
The command line does not respond after you run a command (The instance is not in the Running state)
If the command line does not respond after you run an ali-instance-cli command, the instance may not be in the Running state. To view the instance status, see Check whether the instance is in the Running state in this topic.
The command line does not respond after you run a command (Security group configuration issue)
If the command line does not respond after you run an ali-instance-cli command, the required outbound ports may not be open in the security group. By default, basic security groups allow all outbound traffic. This issue may occur if you modify the outbound rules or use 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.
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 |
| This port is used to access the Cloud Assistant server. |
Allow | 1 | Custom TCP | 443 |
| 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 |
| 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.
The "session manager is disabled, please enable first" error is reported after you run a command
If the session manager is disabled, please enable first error occurs after running an ali-instance-cli command, enable Session Manager in the console.
How to analyze ali-instance-cli logs
Analyze ali-instance-cli logs to identify issues.
Session Manager CLI logs: When you use ali-instance-cli, a log folder (e.g.
~/log/aliyun_ecs_session_log.2022XXXX) is generated in the tool's directory.Cloud Assistant Agent logs:
Linux
/usr/local/share/aliyun-assist/<Cloud Assistant Agent version>/log/Windows
C:\ProgramData\aliyun\assist\<Cloud Assistant Agent version>\log