Connect to an instance with Session Manager CLI (ali-instance-cli)-Elastic Compute Service(ECS)-阿里云帮助中心

You can use Session Manager CLI from your local command line to connect to an ECS instance. This method supports password-free connections to instances that do not have public IP addresses and is more secure and convenient than traditional SSH or RDP connections. This topic describes how to get started with Session Manager CLI.

What is Session Manager CLI?

Session Manager CLI, also known as ali-instance-cli, is a command-line tool from Alibaba Cloud. After installing and configuring it on your local computer, you can use Session Manager from the command line to connect to instances.

You can also use ali-instance-cli with Alibaba Cloud CLI for a complete command-line experience. For more information about Alibaba Cloud CLI, see What is Alibaba Cloud CLI?.

Before you begin

Enable Session Manager

Before you use ali-instance-cli, make sure that Session Manager is enabled for your Alibaba Cloud account. You can enable Session Manager only in the console. Follow these steps:

Go to ECS console - Instances.
In the top navigation bar, select the region and resource group for your target instance.
On the Instance page, find the instance that you want to connect to, and in the Actions column, click Connect.
Click Show Other Logon Methods, find Session Manager, turn on the button to the right of Session Management closed, and follow the on-screen instructions to complete the activation.

Check instance state

You can use Session Manager to connect only to instances that are in the Running state.

Console

You can view the status of the instance on the Instance page in the ECS console.

For information about how to check the status of the instance, see View instance information.

Alibaba Cloud CLI

If you have configured Alibaba Cloud CLI, you can run a command to query the status of the instance. For more information about the API operation, see DescribeInstanceStatus.

The following example shows how to query the status of an instance with the ID i-bp1****** in the China (Hangzhou) region.

aliyun ecs DescribeInstanceStatus --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceId.1 'i-bp1******'

A Status of Running in the output indicates the instance is in the Running state.

{
  "TotalCount": 1,
  "RequestId": "A413****-****-****-****-****611B",
  "PageSize": 1,
  "PageNumber": 1,
  "InstanceStatuses": {
    "InstanceStatus": [
      {
        "Status": "Running",
        "InstanceId": "i-bp1******"
      }
    ]
  }
}

You can also call other API operations to query the instance status. For more information, see DescribeInstances.

API

To query the instance status by calling an API operation, see DescribeInstanceStatus or DescribeInstances.

Check Cloud Assistant Agent

Session Manager relies on Cloud Assistant. You can use one of the following methods to check whether Cloud Assistant Agent is installed on the instance.

Cloud Assistant Agent is pre-installed on ECS instances that are created from public images on or after December 1, 2017. If your instance was created before this date or from a custom image that you uploaded, you must install the agent manually. For more information, see Install Cloud Assistant Agent.

Console

Session Manager is implemented based on Cloud Assistant. You need to install Cloud Assistant Agent on the instance. You can view the status of Cloud Assistant Agent on the ECS Cloud Assistant page in the ECS console.

Cloud Assistant Agent is pre-installed on ECS instances that are created from Alibaba Cloud public images on or after December 1, 2017. For ECS instances created before December 1, 2017, you must manually install Cloud Assistant Agent. For more information, see Install the Cloud Assistant Agent.

For information about how to view the status of the Cloud Assistant Agent and handle anomalies, see Check status and handle anomalies.

Alibaba Cloud CLI

If you have configured Alibaba Cloud CLI, you can run a command to check if Cloud Assistant Agent is installed and supports Session Manager. For more information about the API operation, see DescribeCloudAssistantStatus.

The following example shows how to query the Cloud Assistant status of an instance with the ID i-bp1****** in the China (Hangzhou) region.

aliyun ecs DescribeCloudAssistantStatus --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceId.1 'i-bp1******'

If CloudAssistantStatus (Cloud Assistant running status) is true and SupportSessionManager (whether Session Manager is supported) is also true, you can connect to the instance by using Session Manager.

{
  "TotalCount": 1,
  "PageSize": 1,
  "RequestId": "DB34****-****-****-****-****A749",
  "NextToken": "",
  "PageNumber": 1,
  "InstanceCloudAssistantStatusSet": {
    "InstanceCloudAssistantStatus": [
      {
        "CloudAssistantVersion": "2.2.3.857",
        "SupportSessionManager": true,
        "InstanceId": "i-bp1******",
        "InvocationCount": 4,
        "OSType": "Linux",
        "CloudAssistantStatus": "true",
        "LastHeartbeatTime": "2024-12-10T02:38:04Z",
        "LastInvokedTime": "2024-12-08T16:02:45Z",
        "ActiveTaskCount": 0
      }
    ]
  }
}

API

To check the status of Cloud Assistant Agent on an instance by calling an API operation, see DescribeCloudAssistantStatus.

Prepare RAM user credentials

When you use ali-instance-cli, you must specify the AccessKey pair and Security Token Service (STS) token of the RAM user. When you connect to an instance by using Session Manager, the system verifies whether the RAM user who has the credentials also has the ecs:StartTerminalSession permission.

When you configure a custom policy, you can configure the Resource parameter to specify the ECS instances to which a RAM user can connect by using Session Manager. Sample policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecs:StartTerminalSession",
      "Resource": "*"
    }
  ]
}

For information about the CredentialsURI and STS Token parameters, see 创建AccessKey and 什么是STS

For information about how to grant permissions to a RAM user, see Grant permissions to a RAM user.

Step 1: Set up Session Manager CLI

Note

If you have already installed and configured Session Manager CLI, you can skip this step.

1.1 Install ali-instance-cli

First, install Session Manager CLI (ali-instance-cli) on your local computer. The installation steps differ based on your operating system.

Windows

Download ali-instance-cli for Windows, and save it to a local folder.

In this example, ali-instance-cli.exe is saved to the C:\Users\test folder.

macOS

In the macOS terminal, run the following command to download ali-instance-cli.

curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/mac/ali-instance-cli

After downloading, run the following command to grant execute permission on ali-instance-cli.

chmod a+x ali-instance-cli

Linux

Run the following command to install ali-instance-cli for Linux.

x86 architecture

curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/linux/ali-instance-cli

Arm architecture

curl -O https://aliyun-client-assist.oss-cn-beijing.aliyuncs.com/session-manager/linux_arm/ali-instance-cli

After the download is complete, run the following command to grant the execute permission on ali-instance-cli.

chmod a+x ali-instance-cli

1.2 Configure credentials

When you use ali-instance-cli on your local computer to connect to an Alibaba Cloud instance, you must configure your credentials. For details, see Prepare the credentials of a RAM user.

Windows

Select Start > Run, type cmd, and press the Enter key to open the Command Prompt window.
Switch to the directory where ali-instance-cli.exe is located. This topic uses C:\Users\test as an example.
```
cd C:\Users\test
```
Configure your credentials. You can choose one of the following methods:
AccessKey pair

Run the following command and enter your AccessKey ID, AccessKey secret, and Region ID as prompted.
```
ali-instance-cli.exe configure --mode AK
```
STS token

Run the following command to complete the configuration:
```
ali-instance-cli.exe configure set --mode StsToken --region "<region>" --access-key-id "<ak>"  --access-key-secret "<sk>"   --sts-token "<sts_token>"
```
Replace <region>, <ak>, <sk>, and <sts_token> with your actual Region ID, AccessKey ID, AccessKey secret, and STS token.
CredentialsURI

Run the following command and enter your CredentialsURI and Region ID as prompted.
```
ali-instance-cli.exe configure --mode=CredentialsURI
```
The following output indicates that the configuration is complete.

macOS/Linux

Go to the directory where ali-instance-cli is located. This topic uses the home directory of the current user, ~, as an example.
```
cd ~
```
Configure your credentials.
AccessKey pair

Run the following command and enter your AccessKey ID, AccessKey secret, and Region ID as prompted.
```
./ali-instance-cli configure --mode AK
```
STS token

Run the following command to complete the configuration:
```
./ali-instance-cli configure set --mode StsToken --region "<region>" --access-key-id "<ak>"  --access-key-secret "<sk>"   --sts-token "<sts_token>"
```
Replace <region>, <ak>, <sk>, and <sts_token> with your actual Region ID, AccessKey ID, AccessKey secret, and STS token.
CredentialsURI

Run the following command and enter your CredentialsURI and Region ID as prompted.
```
./ali-instance-cli configure --mode=CredentialsURI
```
The following output indicates that the configuration is complete.

Step 2: Connect with Session Manager

2.1 Obtain the instance ID

Before connecting with Session Manager, you must obtain the target instance ID.

Console

Go to ECS console - Instances.
In the top navigation bar, select the region and resource group for your target instance.
On the Instance page, find the instance that you want to connect to. The instance ID is displayed, as shown in the following figure.

Alibaba Cloud CLI

If you have configured Alibaba Cloud CLI, you can run a command to obtain the instance ID. For more information about the API operation, see DescribeInstances.

This example queries for an instance named SessionManager-example in the China (Hangzhou) region.

aliyun ecs DescribeInstances --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceName 'SessionManager-example'

The value of InstanceId in the response is the instance ID.

API

To query the instance ID by calling an API operation, see DescribeInstances.

2.2 Use the ali-instance-cli session management feature

Windows

In the Command Prompt window, go to the directory where ali-instance-cli.exe is located and run the command to connect to the instance. Replace <instance_id> with the instance ID that you obtained in Step 2.1.

ali-instance-cli.exe session --instance <instance_id>

For example, to connect to the instance with the instance ID i-bp1******, you can enter the following command.

ali-instance-cli.exe session --instance i-bp1******

After the connection is successful, you are directed to the command-line interface of the instance, as shown in the following figure.

macOS/Linux

In the terminal, go to the directory where ali-instance-cli is located and run the command to connect to the instance. Replace <instance_id> with the instance ID that you obtained in Step 2.1.

./ali-instance-cli session --instance <instance_id>

For example, to connect to the instance with the instance ID i-bp1******, enter the following command.

./ali-instance-cli session --instance i-bp1******

After the connection is successful, you are directed to the command-line interface of the instance, as shown in the following figure.

More features

In addition to managing sessions, ali-instance-cli provides the following features:

Access instances without public IP addresses by using port forwarding

The port forwarding feature of ali-instance-cli lets you map a port on an instance to a local port. This allows you to access services on the instance, even if it does not have a public IP address, without needing a proxy or bastion host.
Register a temporary SSH public key

This feature lets you register a temporary SSH public key on an instance, which you can then use with the corresponding private key to establish an SSH connection.

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.

The DeliveryTimeout error indicates that the Cloud Assistant Agent is offline

If you receive a DeliveryTimeout error when you run an ali-instance-cli command, the Cloud Assistant Agent on the instance might be offline. To check the agent's status, see Check that 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.

Automatic session disconnect

After you connect to a target instance by using Session Management, the connection automatically disconnects if it is idle for a long time. The default idle timeout is 3 minutes. You can use the --idle-timeout parameter to customize the maximum idle time.

For example, run the following command to connect to a target instance and configure the session to automatically disconnect after 10 minutes of inactivity.

./ali-instance-cli session --instance instance-id --idle-timeout 600

Note

This feature requires ali-instance-cli to be at or above the following versions:

Linux: 1.2.0.48
Windows: 1.1.0.48
macOS: 1.3.0.48

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

What is Session Manager CLI?

Before you begin

Enable Session Manager

Check instance state

Console

Alibaba Cloud CLI

API

Check Cloud Assistant Agent

Console

Alibaba Cloud CLI

API

Prepare RAM user credentials

Step 1: Set up Session Manager CLI

1.1 Install ali-instance-cli

Windows

macOS

Linux

x86 architecture

Arm architecture

1.2 Configure credentials

Windows

AccessKey pair

STS token

CredentialsURI

macOS/Linux

AccessKey pair

STS token

CredentialsURI

Step 2: Connect with Session Manager

2.1 Obtain the instance ID

Console

Alibaba Cloud CLI

API

2.2 Use the ali-instance-cli session management feature

Windows

macOS/Linux

More features

FAQ

CLI hangs: Instance not running

CLI hangs: Security group issue

The DeliveryTimeout error indicates that the Cloud Assistant Agent is offline

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

Automatic session disconnect

Analyzing ali-instance-cli logs