All Products
Search
Document Center

Elastic Compute Service:StartTerminalSession

Last Updated:Sep 29, 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

Usage notes

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 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.

    • The Cloud Assistant Agent versions that are later than the following ones support the session management feature. If you need to upgrade the Cloud Assistant Agent version, follow the instructions in Upgrade or disable upgrades for Cloud Assistant Agent.

      • Linux operating system: 2.2.3.256
      • Windows operating system: 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 in a region. Each ECS instance can have up to 20 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

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:StartTerminalSessionupdate
  • Instance
    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
    none
none

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 ECS instance. The port is used to forward data. After this parameter is configured, Cloud Assistant Agent forwards data to the specified port. For example, you can set this parameter to 22 for data forwarding over SSH.

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

22
CommandLinestringNo

The command to run after the session is initiated. The command length cannot exceed 512 characters.

Note If you specify the CommandLine parameter, you cannot specify the PortNumber or TargetServer parameter.
ssh root@192.168.0.246
TargetServerstringNo

The IP address of the instance. You can use the IP address to access the destination service in a virtual private cloud (VPC).

Note If this parameter is not empty, PortNumber specifies the port number that is used by the managed instance to access the destination service in the VPC.
192.168.0.246
UsernamestringNo

The username used for connection establishment.

testUser

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.-
403Username.ExceedLimitThe length of the username exceeds the upper limit.The length of the username exceeds the upper limit.
403InvalidOperation.SecurityGroupRuleDeniedThe operation is not allowed by the security group inbound rules of the specified instance.-
403InvalidTargetServer.LengthLimitExceededThe length of the parameter TargetServer exceeded the limit of 128 characters.-
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-07-18The Error code has changedView Change Details
2024-04-28The Error code has changedView Change Details
2024-03-12The Error code has changed. The request parameters of the API has changedView Change Details
2023-08-16The Error code has changed. The request parameters of the API has changedView Change Details
2023-05-12The Error code has changedView Change Details
2023-03-15The Error code has changedView Change Details