Run the send_public_key command of ali-instance-cli to register a public key with an instance and connect to the instance with the corresponding private key instead of a password - Elastic Compute Service

Register a 60-second temporary public key with ali-instance-cli and connect to an ECS instance with the private key instead of a password.

Temporary public keys

Temporary public keys let you connect to instances over SSH without configuring key pairs on the instances. Each time you connect, register a temporary public key valid for 60 seconds, then use the corresponding private key instead of a password.

Note

Temporary public keys are stored on the Cloud Assistant server.

Prerequisites

Enable the Session Manager service

Enable the Session Manager service for your Alibaba Cloud account in the console:

Go to ECS console - Instances.
In the top navigation bar, select the region and resource group for the instance.
On the Instance page, find the target instance and click Connect in the Actions column.
Click Show Other Logon Methods. Find Session Manager. Turn on the switch next to Session Management closed. Then, follow the on-screen instructions to enable the service.

Check whether the instance is in the Running state

Session Manager requires the instance to be in the Running state.

Console

View the instance status on the Instance page in the ECS console.

See View instance information.

Alibaba Cloud CLI

If you have the Alibaba Cloud CLI configured, run the following command to query the instance status. For parameter details, see DescribeInstanceStatus.

This topic uses an instance with the ID i-bp1****** in the China (Hangzhou) region as an example.

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

If Status is Running, the instance is running.

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

You can also use DescribeInstances to query the instance status.

API

See DescribeInstanceStatus or DescribeInstances.

Check whether Cloud Assistant Agent is installed

Session Manager requires Cloud Assistant. Use one of the following methods to check whether Cloud Assistant Agent is installed on the instance.

ECS instances created from official public images after December 1, 2017 have Cloud Assistant Agent preinstalled. For instances created before that date or from uploaded custom images, install Cloud Assistant Agent manually.

Console

Session Manager relies on Cloud Assistant. Install Cloud Assistant Agent on the instance and check its status on the ECS Cloud Assistant page in the ECS console.

Cloud Assistant Agent is pre-installed on ECS instances created from Alibaba Cloud public images after December 1, 2017. For earlier instances, manually install Cloud Assistant Agent. See Install the Cloud Assistant Agent.

See Check Cloud Assistant status and troubleshoot exceptions.

Alibaba Cloud CLI

If you have the Alibaba Cloud CLI configured, run the following command to check Cloud Assistant Agent installation and Session Manager support. For parameter details, see DescribeCloudAssistantStatus.

This topic uses an instance with the ID i-bp1****** in the China (Hangzhou) region as an example.

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

If CloudAssistantStatus is true and SupportSessionManager is true, the instance supports Session Manager connections.

{
  "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

See DescribeCloudAssistantStatus.

Prepare the credentials of a RAM user for Session Manager

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 Create an AccessKey pair and What is Security Token Service (STS)?

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

1. Install and configure the Session Manager CLI

Note

Skip this step if you have already installed and configured the Session Manager CLI.

1.1 Install

Install the Session Manager CLI (ali-instance-cli) on your computer. The installation method varies by operating system.

Windows

Click to download ali-instance-cli for Windows and save it to a local folder.

This topic uses the C:\Users\test folder as an example.

macOS

In the macOS terminal, download ali-instance-cli for macOS:

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

Grant execute permissions:

chmod a+x ali-instance-cli

Linux

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

Grant execute permissions:

chmod a+x ali-instance-cli

1.2 Configure

To connect to an ECS instance with ali-instance-cli, configure identity credentials such as an AccessKey. See Prepare the credentials of a RAM user for Session Manager.

Windows

Click Start > Run, enter cmd, and press the Enter key to open a command prompt window.
Go to the directory of ali-instance-cli.exe. This example uses C:\Users\test.
```
cd C:\Users\test
```
Configure credentials using one of the following methods:
AccessKey

Configure the AccessKey ID, AccessKey secret, and Region ID as prompted:
```
ali-instance-cli.exe configure --mode AK
```
STS Token

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

Enter the Credentials URI and Region ID as prompted:
```
ali-instance-cli.exe configure --mode=CredentialsURI
```
The following output indicates a successful configuration.

macOS/Linux

Go to the directory of ali-instance-cli. This example uses the home directory ~.
```
cd ~
```
Configure credentials:
AccessKey

Configure the AccessKey ID, AccessKey secret, and Region ID as prompted:
```
./ali-instance-cli configure --mode AK
```
STS Token

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

Configure the Credentials URI and Region ID as prompted:
```
./ali-instance-cli configure --mode=CredentialsURI
```
The following output indicates a successful configuration.

2. Register a temporary public key with the instance

2.1 Obtain the ID of the instance

Obtain the ID of the target instance.

2.2 Generate a key pair

Generate a key pair on your computer. The public key file is used as the temporary public key in Step 2.3.

Windows computer

Open Command Prompt and run the following command to generate a key pair.

In this example, the OpenSSH client is used to generate a key pair in the C:\Users\test directory.

ssh-keygen -t rsa -b 2048 -f id_rsa

-t rsa: the Rivest-Shamir-Adleman (RSA) key type.
-b 2048: a key length of 2,048 bits.
-f id_rsa: outputs the key files named id_rsa to the working directory.

Important

You are prompted to enter a passphrase. If set, the passphrase is required each time the private key is used.

Press Enter to skip if you do not need a passphrase.

The public key file id_rsa.pub and private key file id_rsa are generated in the working directory. In this example, the working directory is C:\Users\test.

macOS or Linux computer

Open Terminal and run the following command to generate a key pair.

In this example, the OpenSSH client is used to generate a key pair.

ssh-keygen -t rsa -b 2048 -f id_rsa

-t rsa: the RSA key type.
-b 2048: a key length of 2,048 bits.
-f id_rsa: outputs the key files named id_rsa to the working directory.

Important

You are prompted to enter a passphrase. If set, the passphrase is required each time the private key is used.

Press Enter to skip if you do not need a passphrase.

The public key file id_rsa.pub and private key file id_rsa are generated in the working directory.

2.3 Send the public key as a temporary public key to the instance

Windows computer

Open Command Prompt, go to the directory of ali-instance-cli.exe, and run the following command to register the temporary public key with an instance.

Replace <instance_id> with the instance ID, <public_key_path> with the path of the public key file generated in Step 2.2, and <ecs_username> with the username to assign the temporary public key to:

ali-instance-cli.exe send_public_key --instance <instance_id> --public-key <public_key_path> --user-name <ecs_username>

Example: register the public key at C:\Users\test\id_rsa.pub with instance i-bp1****** and assign it to the ecs-user user:

ali-instance-cli.exe send_public_key --instance i-bp1****** --public-key C:\Users\test\id_rsa.pub --user-name ecs-user

Important

After the command succeeds, connect to the instance with the corresponding private key within 60 seconds.

macOS or Linux computer

Open Terminal, go to the directory of ali-instance-cli, and run the following command to register the temporary public key with an instance.

Replace <instance_id> with the instance ID, <public_key_path> with the path of the public key file generated in Step 2.2, and <ecs_username> with the username to assign the temporary public key to:

./ali-instance-cli send_public_key --instance <instance_id> --public-key <public_key_path> --user-name <ecs_username>

Example: register the public key at ~/id_rsa.pub with instance i-bp1****** and assign it to the ecs-user user:

./ali-instance-cli send_public_key --instance i-bp1****** --public-key ~/id_rsa.pub --user-name ecs-user

Important

After the command succeeds, connect to the instance with the corresponding private key within 60 seconds.

After you run the command, the ERROR: 'install config_ecs_instance_connect' command failed error message appears

If this error appears, the config_ecs_instance_connect Cloud Assistant plug-in failed to install. Rerun the command. If the error persists, install the plug-in manually:

Use the ECS console

Use Cloud Assistant to send the following command to the instance to install and start the config_ecs_instance_connect plug-in.

See Create and run commands.

acs-plugin-manager -e -P config_ecs_instance_connect --params --install

Use the CLI

Note

In this example, i-bp15vhvt43ciprqkxxxx is used as the instance ID. Replace it with your actual instance ID.

aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
 --Type 'RunShellScript' \
 --CommandContent 'acs-plugin-manager -e -P config_ecs_instance_connect --params --install' \
 --InstanceId.1 'i-bp15vhvt43ciprqkxxxx'

3. Connect to the instance over SSH

Important

If you are prompted that the password or public key is incorrect, the public key may have expired. A temporary public key is valid for 60 seconds.

Open Command Prompt or Terminal and run the following command to connect to the instance.

Replace <private_key_path> with the path of the private key file generated in Step 2.2, <ecs-username> with the username specified in Step 2.3, and <ecs_ip> with the public IP address of the instance.

ssh -i <private_key_path> <ecs-username>@<ecs_ip>

Example: connect to instance 223.***.***.187 as ecs-user with private key ~/id_rsa:

ssh -i ~/id_rsa ecs-user@223.***.***.187

You can also use the port forwarding feature of ali-instance-cli to connect to an instance without a public IP address. See Use the port forwarding feature of Session Manager CLI to connect to an instance without a public IP address.

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.

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 is reported after you run a command (Cloud Assistant Agent is offline)

If the DeliveryTimeout error occurs when you run an ali-instance-cli command, Cloud Assistant Agent may be unavailable. Check whether Cloud Assistant Agent is installed on the 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.

The connection is automatically closed due to a long period of inactivity

Session Manager connections close after idle timeout. The default is 3 minutes. Use the --idle-timeout parameter to set a custom idle timeout in seconds.

Example: connect with a 10-minute idle timeout:

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

Note

This feature requires ali-instance-cli version:

Linux: 1.2.0.48
Windows: 1.1.0.48
macOS: 1.3.0.48

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