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

The Session Manager CLI (ali-instance-cli) uses Cloud Assistant and WebSockets to enable TCP port forwarding. This feature lets you directly access services on instances without a public IP address and use an 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 address.

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

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

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

Important

A port forwarding session remains active only while the command-line window is running. If you close the window, the session terminates immediately.

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

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

On Windows

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

# 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

The output Waiting for connections indicates the tunnel is active. You can now access the service on the instance's TARGET_PORT by connecting to 127.0.0.1:<local_port>.

For example, to forward the default Nginx port 80 on the target ECS instance i-bp1****** to port 8080 on your local machine, run .\ali-instance-cli.exe portforward -i i-bp1****** -r 80 -l 8080.

On macOS or Linux

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

#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

The output Waiting for connections indicates the tunnel is active. You can now access the service on the instance's TARGET_PORT by connecting to 127.0.0.1:<local_port>.

For example, to forward the default Nginx port 80 on the target ECS instance i-bp1****** to port 8080 on your local machine, run ./ali-instance-cli portforward -i i-bp1****** -r 80 -l 8080.

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

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

On Windows

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

# 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

The output Waiting for connections indicates the jump server tunnel is established. Traffic to 127.0.0.1:<local_port> is now routed through the jump server to TARGET_IP:TARGET_PORT.

For example, to route traffic to an RDS for MySQL instance with the private endpoint rm-******.mysql.rds.aliyuncs.com:3306 through the ECS jump server i-bp1****** and map it to port 13306 on your local machine, run .\ali-instance-cli.exe portforward -i i-bp1****** -r rm-******.mysql.rds.aliyuncs.com:3306 -l 13306.

On macOS or Linux

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

#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

The output Waiting for connections indicates the jump server tunnel is established. Traffic to 127.0.0.1:<local_port> is now routed through the jump server to TARGET_IP:TARGET_PORT.

For example, to map the RDS for MySQL instance (private endpoint rm-******.mysql.rds.aliyuncs.com:3306) to port 13306 on your local machine through the ECS jump server i-bp1******, run ./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, it may be because the required ports for outbound traffic are not open in the security group. By default, basic security groups allow all outbound traffic. This issue may occur if you change the outbound rules or use an advanced security group. The security group rules are described as follows:

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 security groups 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 the Cloud Assistant Agent may be offline. To check the agent's 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 is reported after you run an ali-instance-cli command, it means Session Manager is disabled. You can enable Session Manager in the console. For more information, see Enable Session Manager.

How to analyze ali-instance-cli logs

When an issue occurs with the Session Manager CLI, you can analyze the logs to identify the cause.

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

View the 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