工作階段文件結構描述 - AWS Systems Manager

工作階段文件結構描述

下列資訊說明工作階段文件的結構描述元素。AWS Systems Manager Session Manager 會使用工作階段文件來判斷要啟動哪種類型的工作階段,例如標準工作階段、連接埠轉送工作階段、或要執行互動式命令的工作階段。

schemaVersion

工作階段文件的結構描述版本。工作階段文件僅支援 1.0 版。

類型:字串

必要:是

description

您為工作階段文件指定的描述。例如,"Document to start port forwarding session with Session Manager" (使用 Session Manager 啟動連接埠轉送工作階段的文件)。

類型:字串

必要:否

sessionType

工作階段文件用來建立的工作階段類型。

類型:字串

必要:是

有效值:InteractiveCommands |NonInteractiveCommands |Port |Standard_Stream

inputs

用於使用此工作階段文件建立的工作階段的工作階段偏好設定。用來建立 Standard_Stream 工作階段的工作階段文件需要此元素。

類型:StringMap

必要:否

s3BucketName

在工作階段結束時,接收工作階段日誌的 Amazon Simple Storage Service (Amazon S3) 儲存貯體。

類型:字串

必要:否

s3KeyPrefix

將日誌傳送到在 s3BucketName 輸入中指定的 Amazon S3 儲存貯體時使用的字首。如需有關搭配使用公用字首與 Amazon S3 中存放的物件的詳細資訊,請參閱《Amazon Simple Storage Service 主控台使用者指南》中的如何使用 S3 儲存貯體中的資料夾?

類型:字串

必要:否

s3EncryptionEnabled

如果設定為 true,則必須加密在 s3BucketName 輸入中指定的 Amazon S3 儲存貯體。

類型:布林值

必要:是

cloudWatchLogGroupName

在工作階段結束時接收工作階段日誌的 Amazon CloudWatch Logs (CloudWatch Logs) 群組的名稱。

類型:字串

必要:否

cloudWatchEncryptionEnabled

如果設定為 true,則必須加密在 cloudWatchLogGroupName 輸入中指定的 日誌群組。

類型:布林值

必要:是

cloudWatchStreamingEnabled

如果設定為 true,工作階段資料日誌的持續串流會傳送到您在 cloudWatchLogGroupName 輸入中指定的日誌群組。如果設定為 false,在工作階段結束時,工作階段日誌會傳送到您在 cloudWatchLogGroupName 輸入中指定的日誌群組。

類型:布林值

必要:是

kmsKeyId

您想要使用的 AWS KMS key 的 ID,以進一步加密本地用戶端機器和您連線的 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體之間的資料。

類型:字串

必要:否

runAsEnabled

如果設定為 true,則必須在 runAsDefaultUser 輸入中指定您將連線的執行個體上存在的使用者帳戶。否則,工作階段將無法啟動。根據預設,使用 AWS Systems Manager SSM Agent 建立的 ssm-user 帳戶來啟動工作階段。僅支援 Run As 功能,以連線到 Linux 執行個體。

類型:布林值

必要:是

runAsDefaultUser

runAsEnabled 輸入設定為 true 時,在 Linux 執行個體上啟動工作階段的使用者帳戶名稱。您為此輸入指定的使用者帳戶必須存在於您要連線的執行個體上;否則,工作階段將無法啟動。

類型:字串

必要:否

idleSessionTimeout

在工作階段結束前,您想要允許的閒置時間長度。此輸入的測量單位為分鐘。

類型:字串

有效值:1-60

必要:否

shellProfile

啟動工作階段時,您根據作業系統指定的套用在工作階段中的偏好設定,例如 shell 偏好設定、環境變數、工作目錄以及執行的多個命令。

類型:StringMap

必要:否

windows

您為 Windows 執行個體上的工作階段指定的 shell 偏好設定、環境變數、工作目錄和命令。

類型:字串

必要:否

linux

您為 Linux 執行個體上的工作階段指定的 shell 偏好設定、環境變數、工作目錄和命令。

類型:字串

必要:否

parameters

一種物件,定義文件接受的參數。如需指定文件參數的詳細資訊,請參閱 頂層元素 中的參數。對於常用的參數,我們建議您將這些參數存放在 Systems Manager Parameter Store,然後參考使用。您在文件的這部分可以參考 StringStringList Parameter Store 參數。您在文件的這部分不能參考 SecureString Parameter Store 參數。您可以使用下列格式參考 Parameter Store 參數。

{{ssm:parameter-name}}

如需 Parameter Store 的詳細資訊,請參閱 AWS Systems ManagerParameter Store

類型:StringMap

必要:否

properties

一個物件,在 StartSession API 操作中使用您指定的其值。

對於用於 InteractiveCommands 工作階段的工作階段文件,屬性物件會包含要在您指定的作業系統上執行的命令。如需詳細資訊,請參閱限制對工作階段中命令之存取權

對於用於 Port 工作階段的工作階段文件,屬性物件會包含應將流量重新引導的目標連接埠號碼。如需範例,請參閱本主題後面部分中的 Port 類型工作階段文件範例。

類型:StringMap

必要:否

Standard_Stream 類型工作階段文件範例

YAML
--- schemaVersion: '1.0' description: Document to hold regional settings for Session Manager sessionType: Standard_Stream inputs: s3BucketName: '' s3KeyPrefix: '' s3EncryptionEnabled: true cloudWatchLogGroupName: '' cloudWatchEncryptionEnabled: true cloudWatchStreamingEnabled: true kmsKeyId: '' runAsEnabled: true runAsDefaultUser: '' idleSessionTimeout: '20' shellProfile: windows: '' linux: ''
JSON
{ "schemaVersion": "1.0", "description": "Document to hold regional settings for Session Manager", "sessionType": "Standard_Stream", "inputs": { "s3BucketName": "", "s3KeyPrefix": "", "s3EncryptionEnabled": true, "cloudWatchLogGroupName": "", "cloudWatchEncryptionEnabled": true, "cloudWatchStreamingEnabled": true, "kmsKeyId": "", "runAsEnabled": true, "runAsDefaultUser": "", "idleSessionTimeout": "20", "shellProfile": { "windows": "date", "linux": "pwd;ls" } } }

InteractiveCommands 類型工作階段文件範例

YAML
--- schemaVersion: '1.0' description: Document to view a log file on a Linux instance sessionType: InteractiveCommands parameters: logpath: type: String description: The log file path to read. default: "/var/log/amazon/ssm/amazon-ssm-agent.log" allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$" properties: linux: commands: "tail -f {{ logpath }}" runAsElevated: true
JSON
{ "schemaVersion": "1.0", "description": "Document to view a log file on a Linux instance", "sessionType": "InteractiveCommands", "parameters": { "logpath": { "type": "String", "description": "The log file path to read.", "default": "/var/log/amazon/ssm/amazon-ssm-agent.log", "allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$" } }, "properties": { "linux": { "commands": "tail -f {{ logpath }}", "runAsElevated": true } } }

Port 類型工作階段文件範例

YAML
--- schemaVersion: '1.0' description: Document to open given port connection over Session Manager sessionType: Port parameters: paramExample: type: string description: document parameter properties: portNumber: anyPortNumber
JSON
{ "schemaVersion": "1.0", "description": "Document to open given port connection over Session Manager", "sessionType": "Port", "parameters": { "paramExample": { "type": "string", "description": "document parameter" } }, "properties": { "portNumber": "anyPortNumber" } }

含特殊字元的工作階段文件範例

YAML
--- schemaVersion: '1.0' description: Example document with quotation marks sessionType: InteractiveCommands parameters: Test: type: String description: Test Input maxChars: 32 properties: windows: commands: | $Test = '{{ Test }}' $myVariable = \"Computer name is $env:COMPUTERNAME\" Write-Host "Test variable: $myVariable`.`nInput parameter: $Test" runAsElevated: false
JSON
{ "schemaVersion":"1.0", "description":"Test document with quotation marks", "sessionType":"InteractiveCommands", "parameters":{ "Test":{ "type":"String", "description":"Test Input", "maxChars":32 } }, "properties":{ "windows":{ "commands":[ "$Test = '{{ Test }}'", "$myVariable = \\\"Computer name is $env:COMPUTERNAME\\\"", "Write-Host \"Test variable: $myVariable`.`nInput parameter: $Test\"" ], "runAsElevated":false } } }