Create Session Manager preferences (command line) - AWS Systems Manager

Create Session Manager preferences (command line)

The following procedure describes how to use your preferred command line tool to create Session Manager preferences for your account in the selected AWS Region. Use Session Manager preferences to specify options for logging session data in an S3 bucket or Amazon CloudWatch Logs log group. You can also use Session Manager preferences to encrypt your session data.

For information about using command line tools to update existing Session Manager preferences, see Update Session Manager preferences (command line).


You can use this procedure to create custom session documents for your Session Manager preferences that override account level settings. When you create your custom session documents, specify a value other than SSM-SessionManagerRunShell for the name parameter and modify the inputs as needed. To use your custom session documents, you must provide the name of your custom session document for the --document-name parameter when starting a session from the AWS CLI. When you start a session from the console, you can't specify custom session documents.

To create Session Manager preferences (command line)

  1. Create a JSON file on your local machine with a name such as SessionManagerRunShell.json, and then paste the following content into it:

    { "schemaVersion": "1.0", "description": "Document to hold regional settings for Session Manager", "sessionType": "Standard_Stream", "inputs": { "s3BucketName": "", "s3KeyPrefix": "", "s3EncryptionEnabled": true, "cloudWatchLogGroupName": "", "cloudWatchEncryptionEnabled": true, "kmsKeyId": "", "runAsEnabled": false, "runAsDefaultUser": "" } }
  2. Specify where you want to send session data. You can specify an S3 bucket name (with an optional prefix) or a CloudWatch Logs log group name. If you want to further encrypt data between local client and EC2 instances, provide the AWS KMS key to use for encryption. The following is an example.

    { "schemaVersion": "1.0", "description": "Document to hold regional settings for Session Manager", "sessionType": "Standard_Stream", "inputs": { "s3BucketName": "DOC-EXAMPLE-BUCKET", "s3KeyPrefix": "MyBucketPrefix", "s3EncryptionEnabled": true, "cloudWatchLogGroupName": "MyLogGroupName", "cloudWatchEncryptionEnabled": true, "kmsKeyId": "MyKMSKeyID", "runAsEnabled": true, "runAsDefaultUser": "MyDefaultRunAsUser" } }

    If you do not want to encrypt the session log data, change "true" to "false" for s3EncryptionEnabled.

    If you aren't sending logs to either an S3 bucket or a CloudWatch Logs log group, don't want to encrypt active session data, or don't want to enable Run As support for the sessions in your account, you can delete the lines for those options. Make sure the last line in the "inputs" section does not end with a comma.

    If you add a AWS KMS key ID to encrypt your session data, both the users who start sessions and the instances that they connect to must have permission to use the key. You provide permission to use the CMK with Session Manager through IAM policies. For information, see the following topics:

  3. Save the file.

  4. In the directory where you created the JSON file, run the following command:

    aws ssm create-document \ --name SSM-SessionManagerRunShell \ --content "file://SessionManagerRunShell.json" \ --document-type "Session" \ --document-format JSON
    aws ssm create-document ^ --name SSM-SessionManagerRunShell ^ --content "file://SessionManagerRunShell.json" ^ --document-type "Session" ^ --document-format JSON
    New-SSMDocument ` -Name "SSM-SessionManagerRunShell" ` -Content (Get-Content -Raw SessionManagerRunShell.json) ` -DocumentType "Session" ` -DocumentFormat JSON

    If successful, the command returns output similar to the following:

        "DocumentDescription": {
            "Status": "Creating",
            "Hash": "ce4fd0a2ab9b0fae759004ba603174c3ec2231f21a81db8690a33eb66EXAMPLE",
            "Name": "SSM-SessionManagerRunShell",
            "Tags": [],
            "DocumentType": "Session",
            "PlatformTypes": [
            "DocumentVersion": "1",
            "HashType": "Sha256",
            "CreatedDate": 1547750660.918,
            "Owner": "111122223333",
            "SchemaVersion": "1.0",
            "DefaultVersion": "1",
            "DocumentFormat": "JSON",
            "LatestVersion": "1"