Session management is a feature provided by Cloud Assistant that allows you to connect to Elastic Compute Service (ECS) instances in a secure and convenient manner. ali-instance-cli is a CLI used for session management. This topic describes how to use ali-instance-cli to connect to an ECS instance over SSH.

Prerequisites

  • The Cloud Assistant client is installed on the ECS instance to which you want to connect. For a Windows instance, the installed client version must be 2.1.3.256 or later. For a Linux instance, the installed client version must be 2.2.3.256 or later. For more information, see Install the Cloud Assistant client.
  • For information about how to enable the session management feature, see Connect to an instance by using session management.

Background information

When you use ali-instance-cli to connect to an ECS instance over SSH, you need to only provide the ID and password of the instance. You do not need to expose the public IP address and port number of the instance. This connection method is more convenient and secure than using SSH or Virtual Network Console (VNC). For more information about session management, see How session management works.

Session management clients support Linux, macOS, and Windows operating systems and are used differently on these operating systems. For more information, see the following sections in this topic:

Linux and macOS operating systems

  1. Log on to a session management client.
  2. Install ali-instance-cli on the session management client.
    Run commands to install ali-instance-cli based on the following operating system types:
    • Linux
      curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/linux/ali-instance-cli
      chmod a+x ali-instance-cli
    • macOS
      curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/mac/ali-instance-cli
      chmod a+x ali-instance-cli
  3. Create a file named config and add configurations to the file.
    1. Create the .ssh directory in the current working directory. In this example, /home/test is used as the working directory.
      mkdir .ssh
    2. Switch to the .ssh directory.
      cd .ssh
    3. Create and open the config file.
      vim config
    4. Press the I key to enter the edit mode.
    5. Add the following content to the config file.
      Note Replace ali-instance-cli in the following command with the absolute path of the ali-instance-cli file. In this example, /home/test/ali-instance-cli is used.
      host i-*
          ProxyCommand sh -c "ali-instance-cli ssh -i '%h' --port  '%p'" 
    6. Press the Esc key to exit the edit mode.
    7. Enter :wq and press the Enter key to save and close the file.
    8. Grant the execute permissions on the config file.
      chmod 755 config
  4. Configure an AccessKey pair, a Security Token Service (STS) token, or CredentialsURI.
    For information about how to obtain an AccessKey pair or STS token, see Obtain an AccessKey pair or What is STS?.
    1. Switch to the test directory.
      cd /home/test
    2. Configure an authentication method.

      The following authentication methods are supported:

      • AccessKey pair-based authentication
        Run the following command and enter an AccessKey ID, AccessKey secret, and region ID as prompted:
        ./ali-instance-cli configure --mode AK
      • STS token-based authentication
        Note Replace region, ak, sk, and token with the actual region ID, AccessKey ID, AccessKey secret, and STS token.
        ./ali-instance-cli configure set --mode StsToken --region "region" --access-key-id "ak"  --access-key-secret "sk"   --sts-token "token"
      • CredentialsURI-based authentication
        Run the following command and specify CredentialsURI and RegionID as prompted.
        Note Set the CredentialsURI value to the IP address of the authentication server that you configure.
        ./ali-instance-cli configure --mode=CredentialsURI
      A command output similar to the following one indicates that the AccessKey pair-based authentication method is configured. Authentication method configured
  5. Run an SSH command to connect to an ECS instance.
    You can use a username and password pair or a key pair to connect to the instance.
    Note Replace user and aliyun instance id with the actual username and ID of the instance.
    • Run the following command to connect to the instance with a username and password pair:
      ssh user@aliyun instance id
    • Run the following command to connect to the instance with a key pair:
      ssh -i key.pem user@aliyun instance id
    A command output similar to the following one indicates that you are connected to the instance over SSH by using session management. Instance connected

Windows operating systems

Before you use a session management client that runs a Windows operating system to connect to an ECS instance, make sure that OpenSSH is installed on the client.For more information, see Use Cloud Assistant to install OpenSSH on an ECS Windows instance.

  1. Log on to a session management client.
    For more information, see Connection methods.
  2. Download ali-instance-cli to the session management client.

    Download and save ali-instance-cli.exe for Windows to a directory on the session management client. In this example, the C:\Users\test directory is used.

  3. Create a file named config and add configurations to the file.
    1. In the C:\Users\<Username> directory, create a folder named .ssh.
      Note Replace C:\Users\<Username> with the actual directory. In this example, C:\Users\test is used.
    2. In the .ssh folder, create a file named config.
    3. Add the following content to the config file.

      Replace ali-instance-cli.exe with the absolute path of the ali-instance-cli.exe file. In this example, C:\Users\test\ali-instance-cli.exe is used.

      host i-*
          ProxyCommand C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe "ali-instance-cli.exe ssh -i '%h' --port  '%p'"
  4. Configure an AccessKey pair or an STS token.
    For information about how to obtain an AccessKey pair or STS token, see Obtain an AccessKey pair or What is STS?.
    1. Choose Start > Run, enter cmd, and then press the Enter key to open the Command Prompt window.
    2. Switch to the test directory.
      cd C:\Users\test
    3. Configure an authentication method.

      The following authentication methods are supported:

      • AccessKey pair-based authentication
        Run the following command and enter an AccessKey ID, AccessKey secret, and region ID as prompted:
        ali-instance-cli.exe configure --mode AK
      • STS token-based authentication
        Note Replace region, ak, sk, and token with the actual region ID, AccessKey ID, AccessKey secret, and STS token.
        ali-instance-cli.exe configure set --mode StsToken --region "region" --access-key-id "ak"  --access-key-secret "sk"   --sts-token "token"
      • CredentialsURI-based authentication
        Run the following command and specify CredentialsURI and RegionID as prompted:
        ./ali-instance-cli configure --mode=CredentialsURI

      A command output similar to the following one indicates that the AccessKey pair-based authentication method is configured.

      Authentication method configured
  5. Run an SSH command to connect to an ECS instance.
    You can use a username and password pair or a key pair to connect to the instance.
    Note Replace user and aliyun instance id with the actual username and ID of the instance.
    • Run the following command to connect to the instance with a username and password pair:
      ssh user@aliyun instance id
    • Run the following command to connect to the instance with a key pair:
      ssh -i key.pem user@aliyun instance id

    A command output similar to the following one indicates that you are connected to the instance over SSH by using session management.

    Instance connected

FAQ

If an error occurs when you use a session management client, you can view logs to identify the error cause.
  • View the log generated at the current time for the session management client. Example: /home/test/log/aliyun_ecs_session_log.2022XXXX.
  • View logs of the Cloud Assistant client in one of the following directories based on the operating system type.
    • Linux
      /usr/local/share/aliyun-assist/<Version number of Cloud Assistant>/log/
    • Windows
      C:\ProgramData\aliyun\assist\<Version number of Cloud Assistant>\log

If the session management feature is not enabled when you use the session management client to connect to an instance, the ssh_exchange_identification: Connection closed by remote host error is reported. Additionally, the session manager is disabled, please enable first entry appears in the session management client log. You can enable the session management feature in the ECS console. For more information, see Connect to an instance by using session management.