StartTerminalSession-阿里云帮助中心

Invoke StartTerminalSession to create a session based on the Session Manager feature. You can establish a WebSocket session with an ECS instance by specifying its instance ID. Use the WebSocketUrl returned by the API to remotely connect to the ECS instance.

Operation description

API Guide

When you customize a remote connection client through code, you can invoke this API to obtain the WebSocketUrl for remotely connecting to an ECS instance. Note the following when invoking this API:

The specified ECS instance must be in the running state.
The specified ECS instance must have the Cloud Assistant Agent installed. You can invoke DescribeCloudAssistantStatus to check whether the Cloud Assistant Agent is installed on the ECS instance and to query its version number.
- If the Cloud Assistant Agent is not installed on your ECS instance, invoke InstallCloudAssistant to install it.
- The Cloud Assistant Agent version must be higher than the following versions to support the Session Manager feature. To upgrade the Cloud Assistant Agent version, see Upgrade or disable automatic upgrade of Cloud Assistant Agent.
  - Linux operating system: 2.2.3.256
  - Windows operating system: 2.1.3.256
After successful invocation of this API, the WebSocketUrl remains valid for 10 minutes.
If no data transmission occurs within 3 minutes after the session is established, Cloud Assistant shuts down the connection.
Within the same Region, the number of created and active sessions cannot exceed 1,000. The number of sessions in Connection Status per ECS instance cannot exceed 20. The bandwidth limit for a single session is 200 kb/s.
The port forwarding feature currently supports TCP port forwarding only and does not support UDP.
To permanently close a session and invalidate the WebSocketUrl, invoke the EndTerminalSession API.

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. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
RegionId	string	Yes	The region ID. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
InstanceId	array	Yes	The instance IDs.
	string	No	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****
PortNumber	integer	No	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
CommandLine	string	No	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
TargetServer	string	No	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
Username	string	No	The username used for connection establishment.	testUser
ConnectionType	string	No	The network type of the WebSocket URL required to connect to the instance. Valid values: Internet (default) Intranet	Intranet
PasswordName	string	No	The password name of the user when using Session Manager on a Windows instance. The length cannot exceed 255 characters. When you want to use Session Manager on a Windows instance as a non-default user (System), you must pass both Username and this parameter. To reduce the risk of password disclosure, store the plaintext password in the parameter repository of CloudOps Orchestration Service, and pass only the password name here. For more information, see encrypted parameters.	axtSecretPassword
ClientToken	string	No	Ensures the idempotence of the request. Generate a unique parameter value from your client to guarantee uniqueness across different requests. ClientToken supports only ASCII characters and must not exceed 64 characters. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-426655440000
EncryptionOptions	object	No	Session encryption configuration items.
Enabled	boolean	No	Enable end-to-end encryption for the session connection.	true
KMSKeyId	string	No	KMS key ID. Notes: Only KMS symmetric keys are supported. This parameter can be specified only when the encryption mode is Kms.	xxx
Mode	string	No	Encryption mode. Valid values: Auto: Use autonegotiation to encrypt the session with a secret key. Kms: Use a KMS key to encrypt the session. Default value: Auto. Notes: 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 included in the WebSocket request header. The system uses this token to authenticate the request.	d86c2df2-d19c-4bd8-b817-a19ef123****
WebSocketUrl	string	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

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.