StartTerminalSession -

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 (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 number of the installed Cloud Assistant Agent version.
- If Cloud Assistant Agent is not installed on the ECS instance, call the InstallCloudAssistant operation to install Cloud Assistant Agent.
- The Cloud Assistant Agent version that is installed on the instance must be later than one of the following versions to support Session Manager. 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: V2.2.3.256
  - For Windows operating systems: V2.1.3.256
Each WebSocket URL returned by the StartTerminalSession operation is valid for 10 minutes.
Up to 1,000 sessions can be created and remain available per 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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	StartTerminalSession	The operation that you want to perform. Set the value to StartTerminalSession.
RegionId	String	Yes	cn-hangzhou	The region ID of the ECS instance. You can call the DescribeRegions operation to query the most recent region list.
InstanceId.N	String	Yes	i-bp1eifrtpxa9tb****	The ID of ECS instance N. You can specify the IDs of up to 10 ECS instances in a single request. Valid values of N: 1 to 10.
PortNumber	Integer	No	22	The port number of the ECS instance, which is used to forward data. If you specify this parameter, Cloud Assistant Agent forwards data to the specified port for port forwarding. Example: 22. This parameter is empty by default, which indicates that no port number is configured to forward data.
CommandLine	String	No	ssh root@192.168.0.246	The command to run after the session is initiated. The command can be up to 512 characters in length. Note If you specify `CommandLine`, you do not need to specify `PortNumber` or `TargetServer`.
TargetServer	String	No	192.168.0.246	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.

Response parameters

Parameter	Type	Example	Description
RequestId	String	EB5173B0-8E80-564E-AAD1-3135412*****	The ID of the request.
SessionId	String	s-hz023od0x9****	The ID of the session.
SecurityToken	String	d86c2df2-d19c-4bd8-b817-a19ef123****	The security token included in the WebSocket request header. The system uses this token to authenticate the request.
WebSocketUrl	String	wss://cn-hangzhou.axt.aliyuncs.com/session?sessionId=s-hz023od0x9**&token=d86c2df2-d19c-4bd8-b817-a19ef123**	The URL of the WebSocket session that is established to the instance. The URL includes the session ID (`SessionId`) and the authentication token (`SecurityToken`).

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=StartTerminalSession
&RegionId=cn-hangzhou
&InstanceId.1=i-bp1eifrtpxa9tb****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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.	This operation cannot be performed in the specified region. Check whether the value of the RegionId parameter is valid.
400	PortNumber.Invalid	The port number is invalid.	Invalid PortNumber value.
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	The maximum number of instance IDs is exceeded.
403	SessionCount.ExceedLimit	The number of sessions exceeds the upper limit.	The maximum number of sessions in the connected state is exceeded.
403	Operation.Forbidden	The operation is not permitted.	The operation is not supported.
403	PortForwarding.NotSupported	Port forwarding is not supported currently.	The port forwarding feature is not supported.
403	UserBehavior.SessionManagerDisabled	The api is disabled by user behavior.	Session Manager is disabled. We recommend that you enable Session Manager for all regions in your account.
403	InvalidCommandLine.Conflict	The parameter PortNumber or TargetServer cannot be specified with parameter CommandLine.	The PortNumber or TargetServer parameter is mutually exclusive with the CommandLine parameter.
403	InvalidTargetServer.MissingPortNumber	The parameter PortNumber must be specified with parameter TargetServer.	The PortNumber parameter must be specified together with the TargetServer parameter.
403	InvalidCommandLine.LengthLimitExceeded	The length of the parameter CommandLine exceeded the limit of 512 characters.	Invalid CommandLine value. The specified command exceeds 512 characters in length.
403	InvalidInstanceIds.CountLimitExceeded	The count of Instances exceeded the maximum limit of 1 when TargetServer or CommandLine parameter was specified.	The maximum number of instances is exceeded. When the TargetServer or CommandLine parameter is specified, only one instance can be specified.
404	InvalidInstance.NotFound	The specified instances not found.	The specified instance ID is not found.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	An error occurred when the request was being sent. Try again later.

For a list of error codes, see Service error codes.