AWSSupport-EnableWindowsEC2SerialConsole
Description
The runbook AWSSupport-EnableWindowsEC2SerialConsole
helps you enable Amazon EC2
Serial Console, Special Admin Console (SAC), and boot menu on your Amazon EC2 Windows instance.
With Amazon Elastic Compute Cloud (Amazon EC2) Serial Console feature, you have access to your Amazon EC2 instance's
serial port to troubleshoot boot, network configuration, and other issues. The runbook
automates the steps required to enable the feature on instances in running state and managed
by AWS Systems Manager, as well as ones in stopped state or not managed by AWS Systems Manager.
How does it work?
The AWSSupport-EnableWindowsEC2SerialConsole
automation runbook helps to
enable SAC and boot menu on Amazon EC2 instances running Microsoft Windows Server. For instances
in running state and managed by AWS Systems Manager, the runbook runs an AWS Systems Manager Run Command
PowerShell script to enable SAC and boot menu. For instances in stopped state or not managed
by AWS Systems Manager, the runbook uses the AWSSupport-StartEC2RescueWorkflow to create a temporary Amazon EC2 instance to
perform the required changes offline.
For more information see Amazon EC2 Serial Console for Windows instances.
Important
-
If you enable SAC on an instance, the Amazon EC2 services that rely on password retrieval will not work from the Amazon EC2 console. For more information, see Use SAC to troubleshoot your Windows instance.
-
To configure access to the serial console, you must grant serial console access at the account level and then configure AWS Identity and Access Management (IAM) policies to grant access to your users. You must also configure a password-based user on every instance so that your users can use the serial console for troubleshooting. For more information see Configure access to the Amazon EC2 Serial Console.
-
To see if the serial console is enabled on your account see View account access status to the serial console.
-
Serial console access is only supported on virtualized instances built on the Nitro System.
For more information, see the Amazon EC2 Serial Console Prerequisites.
Document type
Automation
Owner
Amazon
Platforms
Windows
Parameters
Required IAM permissions
The AutomationAssumeRole
parameter requires the following actions to
use the runbook successfully.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "autoscaling:DescribeAutoScalingInstances", "ec2:GetSerialConsoleAccessStatus", "ec2:Describe*", "ec2:createTags", "ec2:createImage", "ssm:DescribeAutomationExecutions", "ssm:DescribeInstanceInformation", "ssm:GetAutomationExecution", "ssm:ListCommandInvocations", "ssm:ListCommands" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:AttachVolume", "ec2:DetachVolume", "ec2:ModifyInstanceAttribute", "ec2:RebootInstances", "ec2:StartInstances", "ec2:StopInstances", "iam:GetInstanceProfile", "ssm:GetParameters", "ssm:SendCommand", "ssm:StartAutomationExecution" ], "Resource": [ "arn:${Partition}:ec2:${Region}:${AccountId}:instance/${InstanceId}", "arn:${Partition}:ec2:${Region}:${AccountId}:volume/${VolumeId}", "arn:${Partition}:iam::${AccountId}:instance-profile/${InstanceProfileName}", "arn:${Partition}:ssm:${Region}::parameter/aws/service/*", "arn:${Partition}:ssm:${Region}::automation-definition/AWSSupport-StartEC2RescueWorkflow:*", "arn:${Partition}:ssm:${Region}::document/AWS-ConfigureAWSPackage", "arn:${Partition}:ssm:${Region}::document/AWS-RunPowerShellScript" ] }, { "Effect": "Allow", "Action": [ "cloudformation:CreateStack" ], "Resource": "*", "Condition": { "StringLike": { "aws:RequestTag/Name": "AWSSupport-EC2Rescue: *" }, "ForAllValues:StringEquals": { "aws:TagKeys": [ "AWSSupport-EC2Rescue-AutomationExecution", "Name" ] } } }, { "Effect": "Allow", "Action": [ "cloudformation:DeleteStack", "cloudformation:DescribeStackEvents", "cloudformation:DescribeStackResource", "cloudformation:DescribeStacks", "ec2:AttachVolume", "ec2:DetachVolume", "ec2:RebootInstances", "ec2:StopInstances", "ec2:TerminateInstances", "ssm:SendCommand" ], "Resource": "*", "Condition": { "StringLike": { "aws:ResourceTag/Name": "AWSSupport-EC2Rescue: *" } } }, { "Effect": "Allow", "Action": [ "ec2:CreateLaunchTemplate", "ec2:DeleteLaunchTemplate", "ec2:RunInstances" ], "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "aws:CalledVia": [ "cloudformation.amazonaws.com" ] } } }, { "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "*", "Condition": { "StringLikeIfExists": { "iam:PassedToService": [ "ssm.amazonaws.com", "ec2.amazonaws.com" ] } } } ] }
Instructions
Follow these steps to configure the automation:
-
Navigate to the
AWSSupport-EnableWindowsEC2SerialConsole
in the AWS Systems Manager console. -
Select Execute automation.
-
For the input parameters, enter the following:
-
InstanceId: (Required)
The ID of the Amazon EC2 instance that you want to enable Amazon EC2 serial console, (SAC), and boot menu.
-
AutomationAssumeRole: (Optional)
The Amazon Resource Name (ARN) of the IAM role that allows Systems Manager Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses the permissions of the user who starts this runbook.
-
HelperInstanceType: (Conditional)
The type of Amazon EC2 instance that the runbook provisions to configure Amazon EC2 serial console for an offline instance.
-
HelperInstanceProfileName: (Conditional)
The name of an existing IAM instance profile for the helper instance. If you are enabling SAC and boot menu on an instance that is in stopped state or not managed by AWS Systems Manager, this is required. If an IAM instance profile is not specified, the automation creates one on your behalf.
-
SubnetId: (Conditional)
The subnet ID for a helper instance. By default, it uses the the same subnet where the provided instance resides.
Important
If you provide a custom subnet, it must be in the same Availability Zone as InstanceId, and it must allow access to the Systems Manager endpoints. This is only required if the target instance is in stopped state or is not managed by AWS Systems Manager.
-
CreateInstanceBackupBeforeScriptExecution: (Optional)
Specify True to create an Amazon Machine Images (AMI) backup of the Amazon EC2 instance before enabling SAC and boot menu. The AMI will persist after the automation completes. It is your responsibility to secure access to the AMI or delete it.
-
BackupAmazonMachineImagePrefix: (Conditional)
A prefix for the Amazon Machine Image (AMI) that is created if the
CreateInstanceBackupBeforeScriptExecution
parameter is set toTrue
.
-
-
Select Execute.
-
The automation initiates.
-
The document performs the following steps:
-
CheckIfEc2SerialConsoleAccessEnabled:
Checks if Amazon EC2 Serial Console access is enabled at the account level. Note: Access to the serial console is not available by default. For more information see Configure access to the Amazon EC2 Serial Console.
-
CheckIfEc2InstanceIsWindows:
Asserts if the target instance platform is Windows.
-
GetInstanceType:
Retrieves the instance type of the target instance.
-
CheckIfInstanceTypeIsNitro:
Checks if the instance type hypervisor is Nitro-based. Serial Console Access is only supported on virtualized instances built on the Nitro System.
-
CheckIfInstanceIsInAutoScalingGroup:
Checks if the Amazon EC2 instance is part of an Amazon EC2 Auto Scaling group by calling the
DescribeAutoScalingInstances
API. If the instance is part of an Amazon EC2 Auto Scaling group, it ensures that the Porting Assistant for .NET instance is in Standby lifecycle state. -
WaitForEc2InstanceStateStablized:
Waits for the instance to be in running or stopped state.
-
GetEc2InstanceState:
Gets the current state of the instance.
-
BranchOnEc2InstanceState:
Branches based on the instance state retrieved in the previous step. If that instance state is running, it goes to the
CheckIfEc2InstanceIsManagedBySSM
step and if not, it goes to theCheckIfHelperInstanceProfileIsProvided
step. -
CheckIfEc2InstanceIsManagedBySSM:
Checks if the instance is managed by AWS Systems Manager. If managed, the runbook enables SAC and boot menu using a PowerShell Run Command.
-
BranchOnPreEC2RescueBackup:
Branches based on the
CreateInstanceBackupBeforeScriptExecution
input parameter. -
CreateAmazonMachineImageBackup:
Creates an AMI backup of the instance.
-
EnableSACAndBootMenu:
Enables SAC and boot menu by running a PowerShell Run Command script.
-
RebootInstance:
Reboots the Amazon EC2 instance to apply the configuration. This is the final step if the instance is online and is managed by AWS Systems Manager.
-
CheckIfHelperInstanceProfileIsProvided:
Checks if the
HelperInstanceProfileName
specified exists before enabling SAC and boot menu offline using a temporary Amazon EC2 instance. -
RunAutomationToInjectOfflineScriptForEnablingSACAndBootMenu:
Runs the
AWSSupport-StartEC2RescueWorkflow
to enable SAC and boot menu when the instance is in stopped state or not managed by AWS Systems Manager. -
GetExecutionDetails:
Retrieves Image ID of backup and offline script output.
-
-
After completed, review the Outputs section for the detailed results of the execution:
-
EnableSACAndBootMenu.Output:
Output of the command execution in the
EnableSACAndBootMenu
step. -
GetExecutionDetails.OfflineScriptOutput:
Output of the offline script executed in the
RunAutomationToInjectOfflineScriptForEnablingSACAndBootMenu
step. -
GetExecutionDetails.BackupBeforeScriptExecution:
Image ID of the AMI backup taken if
CreateInstanceBackupBeforeScriptExecution
input parameter is True.
-
Output of execution on an instance that is running and managed by AWS Systems Manager
![Console output showing successful operations and pending execution details.](/images/systems-manager-automation-runbooks/latest/userguide/images/awssupport-enable-windows-ec2-serial-console_outputs_online.png)
Output of execution on an instance that is stopped or not managed by AWS Systems Manager
![Console output showing offline script execution details and successful operations.](/images/systems-manager-automation-runbooks/latest/userguide/images/awssupport-enable-windows-ec2-serial-console_outputs_offline.png)
References
Systems Manager Automation