All Products
Search
Document Center

Elastic Compute Service:StartTerminalSession

Last Updated:Mar 19, 2024

Creates a session by using the session management feature. When you call this operation, you can include the ID of an Elastic Compute Service (ECS) instance in the request to create a WebSocket session for the instance. The URL of the WebSocket session returned by the operation can be used to connect to the instance.

Operation description

The session management feature is in public preview. To use this feature, log on to the ECS console with your Alibaba Cloud account and enable this feature.

When you use custom code to connect to an ECS instance that serves as a client, you can call this operation to obtain the WebSocket URL that is used to connect to the instance. Take note of the following items:

  • The ECS instance must be in the Running (Running) state.

  • Cloud Assistant Agent must be installed on the ECS instance. You can call the DescribeCloudAssistantStatus operation to check whether Cloud Assistant Agent is installed on the ECS instance and query the version number of the installed Cloud Assistant Agent.

    • If Cloud Assistant Agent is not installed on the ECS instance, call the InstallCloudAssistant operation to install Cloud Assistant Agent.

    • Only the Cloud Assistant Agent versions that are later than the following ones support the session management feature. You can upgrade Cloud Assistant Agent. For information about how to upgrade Cloud Assistant Agent, see Update or disable updates for Cloud Assistant Agent.

      • For Linux operating systems: 2.2.3.256
      • For Windows operating systems: 2.1.3.256
  • Each WebSocket URL returned by the StartTerminalSession operation remains valid for 10 minutes.

  • Up to 1,000 sessions can be created and available per region. Each ECS instance can have up to 10 sessions in the connected state.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
InstanceIdarrayYes

The instance IDs.

stringYes

The ID of instance N. You can specify up to 10 instance IDs in a single request. Valid values of N: 1 to 10.

i-bp1eifrtpxa9tb****
PortNumberintegerNo

The port number of the instance. The port is used to forward data. After this parameter is configured, Cloud Assistant Agent forwards data to the specified port for forwarding. Example: 22.

This parameter is empty by default, which indicates that no port is configured to forward data.

22
CommandLinestringNo

If you set this parameter to the IP address of an instance, the PortNumber parameter specifies the port number of the instance.

Note If you specify CommandLine, you do not need to specify PortNumber or TargetServer.
ssh root@192.168.0.246
TargetServerstringNo

The IP address of the instance.

Note If you set this parameter to the IP address of an instance, the PortNumber parameter specifies the port number of the instance.
192.168.0.246

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The request ID.

EB5173B0-8E80-564E-AAD1-3135412*****
SessionIdstring

The session ID.

s-hz023od0x9****
SecurityTokenstring

The security token included in the WebSocket request header. The system uses this token to authenticate the request.

d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrlstring

The URL of the WebSocket session that is used to connect to the instance. The URL includes the session ID (SessionId) and the authentication token (SecurityToken).

wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****

Examples

Sample success responses

JSONformat

{
  "RequestId": "EB5173B0-8E80-564E-AAD1-3135412*****",
  "SessionId": "s-hz023od0x9****",
  "SecurityToken": "d86c2df2-d19c-4bd8-b817-a19ef123****",
  "WebSocketUrl": "wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9****&token=d86c2df2-d19c-4bd8-b817-a19ef123****"
}

Error codes

HTTP status codeError codeError messageDescription
400RegionId.ApiNotSupportedThe api is not supported in this region.The API operation cannot be called in the specified region. Check whether the specified RegionId parameter is valid.
400PortNumber.InvalidThe port number is invalid.The port number is invalid.
403InstanceIds.ExceedLimitThe number of instance IDs exceeds the upper limit.The number of specified instance IDs exceeds the upper limit.
403SessionCount.ExceedLimitThe number of sessions exceeds the upper limit.The number of sessions in the connected state exceeds the upper limit.
403Operation.ForbiddenThe operation is not permitted.The operation is not supported.
403PortForwarding.NotSupportedPort forwarding is not supported currently.Port forwarding is not supported.
403UserBehavior.SessionManagerDisabledThe api is disabled by user behavior.-
403InvalidCommandLine.ConflictThe parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.-
403InvalidTargetServer.MissingPortNumberThe parameter PortNumber must be specified with parameter TargetServer.-
403InvalidCommandLine.LengthLimitExceededThe length of the parameter CommandLine exceeded the limit of 512 characters.-
403InvalidInstanceIds.CountLimitExceededThe count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.-
404InvalidRegionId.NotFoundThe RegionId provided does not exist in our records.The RegionId provided does not exist
404InvalidInstance.NotFoundThe specified instances not found.The specified instance ID does not exist.
500InternalError.DispatchAn error occurred when you dispatched the request.An error occurred while the request is being sent. Try again later.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-03-12The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 403 change
    delete Error Codes: 400
    delete Error Codes: 404
    delete Error Codes: 500
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: Username
2023-08-16The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 403 change
    delete Error Codes: 400
    delete Error Codes: 404
    delete Error Codes: 500
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: CommandLine
    Added Input Parameters: TargetServer
2023-05-12The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 403 change
    delete Error Codes: 404
    delete Error Codes: 500
2023-03-15The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500