Call StartTerminalSession to create a WebSocket session for an ECS instance - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Invokes StartTerminalSession to create a session based on the session management feature. You can establish a WebSocket session with an ECS instance by specifying the instance ID. The WebSocketUrl returned by this operation can be used to establish a remote connection to the ECS instance.

Operation description

When you customize a remote connection client by using code, you can invoke this operation to obtain the WebSocketUrl for establishing a remote connection to an ECS instance. Take note of the following items:

The specified ECS instance must be in the Running state.
Cloud Assistant Agent must be installed on the specified ECS instance. You can invoke DescribeCloudAssistantStatus to check whether Cloud Assistant Agent is installed on the ECS instance and query the version number of Cloud Assistant Agent.
- If Cloud Assistant Agent is not installed on the ECS instance, invoke InstallCloudAssistant to install it.
- The version number of Cloud Assistant Agent must be later than the following versions to support the session management feature. To upgrade Cloud Assistant Agent, see Update or disable updates for Cloud Assistant Agent.
  - Linux operating system: 2.2.3.256
  - Windows operating system: 2.1.3.256
After this operation is invoked, the WebSocketUrl is valid for 10 minutes.
After a session is established, Cloud Assistant closes the connection if no data is transmitted for 3 minutes.
In a single region, a maximum of 100 sessions can be created and active. A maximum of 20 sessions can be in the connected state for a single ECS instance. The bandwidth limit for a single session is 200 KB/s.
The port forwarding feature supports only TCP port forwarding. UDP is not supported.
To permanently shutdown a session and invalidate the WebSocketUrl, invoke the EndTerminalSession operation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:StartTerminalSession

update

*Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the instance. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
RegionId	string	Yes	The region ID of the instance. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
InstanceId	array	Yes	The instance ID list.
	string	No	The instance ID of the specified ECS instance. N indicates that you can specify multiple ECS instances at a time. A maximum of 1 ECS instance can be specified. Valid values of N: 1.	i-bp1eifrtpxa9tb****
PortNumber	integer	No	The port number of the ECS instance for data forwarding. After this parameter is specified, Cloud Assistant Agent forwards data to the specified port for port forwarding. For example, SSH uses port 22. Default value: empty, which indicates that no port number is specified for data forwarding.	22
CommandLine	string	No	The command to run after the session is initiated. The command can be up to 512 characters in length. Note After you specify `CommandLine`, you cannot specify `PortNumber` or `TargetServer`.	ssh root@192.168.0.246
TargetServer	string	No	The address of the destination server in the VPC that you want to access through the instance. Note If this parameter is not empty, `PortNumber` specifies the port number of the destination server in the VPC that you want to access through the managed instance.	192.168.0.246
Username	string	No	The username used for the connection.	testUser
ConnectionType	string	No	The network type of the WebSocket URL required for the remote connection to the instance. Valid values: Internet: the Internet. This is the default value. Intranet: the internal network.	Intranet
PasswordName	string	No	The name of the password for the user when you use Session Manager on a Windows instance. The name can be up to 255 characters in length. When you want to use Session Manager on a Windows instance as a non-default user (System), specify both Username and this parameter. To reduce the risk of password leaks, store the plaintext password in the parameter repository of operations management and specify only the password name here. For more information, see Encryption parameters.	axtSecretPassword
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-426655440000
EncryptionOptions	object	No	The session encryption configuration.
Enabled	boolean	No	Specifies whether to enable end-to-end encryption for the session connection.	true
KMSKeyId	string	No	The KMS key ID. Note: Only KMS symmetric keys are supported. This parameter can be specified only when the encryption mode is set to Kms.	xxx
Mode	string	No	The secret key encryption pattern. Valid values: Auto: uses an automatically negotiated key to encrypt the session. Kms: uses a KMS key to encrypt the session. Default value: Auto. Note: This parameter can be specified only when session encryption is enabled.	Auto

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	EB5173B0-8E80-564E-AAD1-3135412*****
SessionId	string	The session ID.	s-hz023od0x9****
SecurityToken	string	The security token that is appended to the WebSocket request header for system verification of the request.	d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrl	string	The URL of the WebSocket session for the remote connection to the ECS instance. The URL contains the session ID (`SessionId`) and the `SecurityToken` for system verification.	wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9**&token=d86c2df2-d19c-4bd8-b817-a19ef123**

Examples

Success response

JSON format

{
  "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 code	Error code	Error message	Description
400	RegionId.ApiNotSupported	The 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.
400	PortNumber.Invalid	The port number is invalid.
400	InvalidParameter.ConnectionType	The specified parameter ConnectionType is not valid.	The specified parameter ConnectionType is illegal.
400	InvalidClientToken.Malformed	The specified parameter clientToken is not valid.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	An error occurred while the request is being sent. Try again later.
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	The number of specified instance IDs exceeds the upper limit.
403	SessionCount.ExceedLimit	The number of sessions exceeds the upper limit.	The number of sessions in the connected state exceeds the upper limit.
403	Operation.Forbidden	The operation is not permitted.	The operation is not supported.
403	PortForwarding.NotSupported	Port forwarding is not supported currently.	Port forwarding is not supported.
403	UserBehavior.SessionManagerDisabled	The api is disabled by user behavior.
403	InvalidCommandLine.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.
403	InvalidTargetServer.MissingPortNumber	The parameter PortNumber must be specified with parameter TargetServer.
403	InvalidCommandLine.LengthLimitExceeded	The length of the parameter CommandLine exceeded the limit of 512 characters.
403	InvalidInstanceIds.CountLimitExceeded	The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	The length of the username exceeds the upper limit.
403	InvalidOperation.SecurityGroupRuleDenied	The operation is not allowed by the security group inbound rules of the specified instance.
403	InvalidTargetServer.LengthLimitExceeded	The length of the parameter TargetServer exceeded the limit of 128 characters.
403	InvalidOperation.ConnectionTypeUnsupported	The operation is not supported for the parameter ConnectionType.
403	InvalidPasswordName.LengthLimitExceeded	The length of the parameter PasswordName exceeds the limit of 255 characters.
403	InvalidEncryptionOptionsMode.EncryptionDisabled	EncryptionOptions.Mode cannot be specified when encryption is disabled.	The parameter EncryptionOptions.Mode cannot be specified when session encryption is not on.
403	InvalidParameter.EncryptionOptionsKMSKeyId	The specified parameter EncryptionOptions.KMSKeyId is not valid.	The specified parameter EncryptionOptions.KMSKeyId is illegal.
403	InvalidParameter.EncryptionOptionsMode	The specified parameter EncryptionOptions.Mode is not valid.	The specified parameter EncryptionOptions.Mode is illegal.
403	MissingParameter.EncryptionOptionsKMSKeyId	The input parameter EncryptionOptions.KMSKeyId that is mandatory for processing this request is not supplied.	Parameter EncryptionOptions.KMSKeyId cannot be empty.
403	UnsupportedAgentVersion.Encryption	The cloud assistant agent version on instance %s do not support encryption.
403	InvalidEncryptionOptions.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter EncryptionOptions.	When session encryption is enabled, the parameter PortNumber or TargetServer cannot be specified.
403	IdempotentParameterMismatch	The specified parameter has changed while using an already used clientToken.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	A previous idempotent request is being processed. Try again later.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	Region information error
404	InvalidInstance.NotFound	The specified instances not found.	The specified instance ID does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.