工作階段文件結構描述

下列資訊說明工作階段文件的結構描述元素。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 Simple Storage Service (Amazon S3) 儲存貯體時使用的字首。如需有關搭配使用公用字首與 Amazon Simple Storage Service (Amazon S3) 中存放的物件的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的如何使用 S3 儲存貯體中的資料夾？。

類型：字串

必要：否

s3EncryptionEnabled

如果設定為 true，則必須加密在 s3BucketName 輸入中指定的 Amazon Simple Storage Service (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 帳戶來啟動工作階段。僅連線到 Linux 受管節點時支援執行身分功能。

類型：布林值

必要：是

runAsDefaultUser

當 runAsEnabled 輸入設定為 true 時，在 Linux 受管節點上啟動工作階段的使用者帳戶名稱。您為此輸入指定的使用者帳戶必須存在於您要連線的受管節點上；否則，工作階段將無法啟動。

類型：字串

必要：否

idleSessionTimeout

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

類型：字串

有效值：1-60

必要：否

maxSessionDuration

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

類型：字串

有效值：1-1440

必要：否

shellProfile

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

類型：StringMap

必要：否

windows

您為 Windows 受管節點上的工作階段指定的 shell 偏好設定、環境變數、工作目錄和命令。

類型：字串

必要：否

linux

您為 Linux 受管節點上的工作階段指定的 shell 偏好設定、環境變數、工作目錄和命令。

類型：字串

必要：否

parameters

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

{{ssm:parameter-name}}

如需有關 Parameter Store 的詳細資訊，請參閱「AWS Systems Manager Parameter Store」。

類型：StringMap

必要：否

properties

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

對於用於 InteractiveCommands 工作階段的工作階段文件，屬性物件會包含要在您指定的作業系統上執行的命令。您也可以使用 runAsElevated 布林值屬性決定命令是否以 root 執行。如需詳細資訊，請參閱限制對工作階段中命令之存取權。

對於用於 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'
  maxSessionDuration: '60'
  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",
        "maxSessionDuration": "60",
        "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
      }
   }
}