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 tool provided by the session management feature. This topic describes how to use ali-instance-cli to forward network traffic from a local port of your computer to an ECS instance.

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.
Note The ali-instance-cli port forwarding feature is in invitational preview. To use this feature, submit a ticket.

Background information

When you use ali-instance-cli to set up port forwarding on an instance, you do not need to provide the public IP address of the instance but need only to provide the ID and a port number of the instance. Then, you can use a session management client to forward network traffic from a local port of your computer to the instance. This way, you can access the services on the ECS instance in a secure and convenient manner. 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. 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 Create 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
  4. Run the following command to forward network traffic from a local port of your computer to an ECS instance:
    ./ali-instance-cli portforward -i "instance id" -l 8080 -r 80
    Note This example demonstrates how to use session management for port forwarding. In this example, local port 8080 and port 80 of an instance are used. You can specify another port based on your needs and replace instance id with the actual instance ID.
    A command output similar to the following one indicates that a forwarding path is established from the specified local port to the specified instance port by using session management. Port forwarding in Linux

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 Create 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.exe 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 the following command to forward network traffic from a local port of your computer to an ECS instance:
    ali-instance-cli.exe portforward -i "instance id" -l 8080 -r 80
    Note This example demonstrates how to use session management for port forwarding. In this example, local port 8080 and port 80 of an instance are used. You can specify another port based on your needs and replace instance id with the actual instance ID.
    A command output similar to the following one indicates that a forwarding path is established from the specified local port to the specified instance port by using session management. Port forwarding in Windows

Use case: Access the MySQL service on an ECS instance

Assume that the MySQL service is running on port 3306 on your instance. Your computer on which the session management client is installed runs a Linux operating system. You can use ali-instance-cli to access services on an instance from local port 33306 of your computer.

  1. Run the following command to forward traffic from local port 33306 to port 3306 of the instance:
    ./ali-instance-cli portforward -i "instance id" -l 33306 -r 3306
    A command output similar to the following one indicates that a forwarding path is established from the specified local port to the specified instance port by using session management. Connect to MySQL
  2. Run the following command to access the MySQL service on the instance from your computer:
    mysql -uroot -h127.0.0.1 -ppassword --port=33306
    Note Replace password with the MySQL password.
    A command output similar to the following one indicates that the MySQL service on the instance is accessed. Access the MySQL service
    The ali-instance-cli log shows that a new connection is accepted, which is the connection initiated by the MySQL client. CLI logs
  3. Run the exit command to close the connection to MySQL.
    exit
    The ali-instance-cli log shows that the connection is closed. Connection closed

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.