AWSSupport-ResetLinuxUserPassword
Description
The AWSSupport-ResetLinuxUserPassword
runbook helps you reset the password of
a local operating system (OS) user. This runbook is especially helpful for users who need to
access their Amazon Elastic Compute Cloud (Amazon EC2) instances using the serial console. The runbook creates a
temporary Amazon EC2 instance in your Amazon Web Services account and an Amazon Identity and Access Management (IAM) role with
permissions to retrieve an Amazon Secrets Manager secret value containing the password.
The runbook stops your target Amazon EC2 instance, detaches the root Amazon Elastic Block Store (Amazon EBS) volume, and attaches it to the temporary Amazon EC2 instance. Using Run Command, a script runs on the temporary instance to set the password of the OS user that you specify. Then, the root Amazon EBS volume is reattached to your target instance. The runbook also provides an option to create a snapshot of the root volume at the beginning of the automation.
Before you begin
Create an Secrets Manager secret with the value of the password that you want to assign to your OS user. The value must be in plain text. For more information, see Create an Amazon Secrets Manager secret in the Amazon Secrets Manager User Guide.
Considerations
-
We recommend backing up your instance before using this runbook. Consider setting the value of the
CreateSnapshot
parameter asYes
. -
Changing the local user password requires the runbook to stop your instance. When an instance is stopped, any data stored in memory or on instance store volumes is lost. Also, any automatically assigned public IPv4 addresses are released. For more information about what happens when you stop an instance, see Stop and start your instance in the Amazon EC2 User Guide.
-
If the Amazon EBS volumes attached to your target Amazon EC2 instance are encrypted with a customer managed Amazon Key Management Service (Amazon KMS) key, make sure the Amazon KMS key is not
deleted
ordisabled
or your instance will fail to start.
Document type
Automation
Owner
Amazon
Platforms
Linux
Parameters
-
AutomationAssumeRole
Type: String
Description: (Optional) The Amazon Resource Name (ARN) of the Amazon Identity and Access Management (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 that starts this runbook.
-
InstanceId
Type: String
Description: (Required) The ID of the Amazon EC2 Linux instance that contains the OS user password that you want to reset.
-
LinuxUserName
Type: String
Default: ec2-user
Description: (Optional) The OS user account whose password you want to reset.
-
SecretArn
Type: String
Description: (Required) The ARN of your Secrets Manager secret containing the new password.
-
SecurityGroupId
Type: String
Description: (Optional) The ID of the security group to attach to the temporary Amazon EC2 instance. If you don't provide a value for this parameter, the default Amazon Virtual Private Cloud (Amazon VPC) security group is used.
-
SubnetId
Type: String
Description: (Optional) The ID of the subnet that you want to launch the Amazon EC2 temporary instance in to. By default, the automation chooses the same subnet as your target instance. If you choose to provide a different subnet, it must be in the same Availability Zone as the target instance and have access to Systems Manager endpoints.
-
CreateSnapshot
Type: String
Valid values: Yes | No
Default: Yes
Description: (Optional) Determines whether a snapshot of the root volume of your target Amazon EC2 instance is created before the automation runs.
-
StopConsent
Type: String
Valid values: Yes | No
Default: No
Description: Enter
Yes
to acknowledge that your target Amazon EC2 instance will be stopped during this automation. When the Amazon EC2 instance is stopped, any data stored in memory or instance store volumes is lost, and the automatic public IPv4 address is released. For more information, see Stop and start your instance in the Amazon EC2 User Guide.
Required IAM permissions
The AutomationAssumeRole
parameter requires the following actions to
use the runbook successfully.
-
ssm:DescribeInstanceInformation
-
ssm:ListTagsForResource
-
ssm:SendCommand
-
ec2:AttachVolume
-
ec2:CreateSnapshot
-
ec2:CreateSnapshots
-
ec2:CreateVolume
-
ec2:DescribeImages
-
ec2:DescribeInstances
-
ec2:DescribeInstanceStatus
-
ec2:DescribeSnapshotAttribute
-
ec2:DescribeSnapshots
-
ec2:DescribeSnapshotTierStatus
-
ec2:DescribeVolumes
-
ec2:DescribeVolumeStatus
-
ec2:DetachVolume
-
ec2:RunInstances
-
ec2:StartInstances
-
ec2:StopInstances
-
ec2:TerminateInstances
-
cloudformation:CreateStack
-
cloudformation:DeleteStack
-
cloudformation:DescribeStackResource
-
cloudformation:DescribeStacks
-
cloudformation:ListStacks
-
logs:CreateLogDelivery
-
logs:CreateLogGroup
-
logs:DeleteLogDelivery
-
logs:DeleteLogGroup
-
logs:DescribeLogGroups
-
logs:DescribeLogStreams
-
logs:PutLogEvents
Document Steps
-
aws:branch
– Branches based on whether you have provided consent to stopping the target Amazon EC2 instance. -
aws:assertAwsResourceProperty
Ensures the Amazon EC2 instance status is in arunning
orstopped
state. Otherwise, the automation ends. -
aws:executeAwsApi
Gets the Amazon EC2 instance properties. -
aws:executeAwsApi
Gets the root volume properties. -
aws:branch
Branches the automation depending on whether a subnet ID for the temporary Amazon EC2 instance was provided. -
aws:assertAwsResourceProperty
Ensures the subnet that you specify inSubnetId
parameter is in the same Availability Zone as the target Amazon EC2 instance. -
aws:assertAwsResourceProperty
Ensures the target Amazon EC2 instance root volume is an Amazon EBS volume. -
aws:assertAwsResourceProperty
Ensures the Amazon EC2 instance architecture isarm64
orx86_64
. -
aws:assertAwsResourceProperty
Ensures the Amazon EC2 instance shutdown behavior isstop
and notterminate
. -
aws:branch
Ensures the Amazon EC2 instance is not a Spot Instance. Otherwise, the automation ends. -
aws:executeScript
Ensures the Amazon EC2 instance is not part of an auto scaling group. If the instance is part of an auto scaling group, the automation confirms the Amazon EC2 instance is in aStandby
lifecycle state. -
aws:createStack
Creates a temporary Amazon EC2 instance that is used to reset the password for the OS user that you specify. -
aws:waitForAwsResourceProperty
Waits until the newly launched temporary Amazon EC2 instance is running. -
aws:executeAwsApi
Gets the ID of the temporary Amazon EC2 instance. -
aws:waitForAwsResourceProperty
Waits for the temporary Amazon EC2 instance to report as managed by Systems Manager. -
aws:changeInstanceState
Stops the target Amazon EC2 instance. -
aws:changeInstanceState
Forces the target Amazon EC2 instance to stop in case it gets stuck in a stopping state. -
aws:branch
Branches the automation depending on whether a snapshot of the root volume of the target Amazon EC2 instance was requested. -
aws:executeAwsApi
Creates a snapshot of the target Amazon EC2 instance root Amazon EBS volume. -
aws:waitForAwsResourceProperty
Waits for the snapshot to be in acompleted
state. -
aws:executeAwsApi
Detaches the Amazon EBS root volume from the target Amazon EC2 instance. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS root volume to be detached from the target Amazon EC2 instance. -
aws:executeAwsApi
Attaches the root Amazon EBS volume to the temporary Amazon EC2 instance. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS root volume to be attached to the temporary Amazon EC2 instance. -
aws:runCommand
Resets the target user password by running a shell script using Run Command on the temporary Amazon EC2 instance. -
aws:executeAwsApi
Detaches the Amazon EBS root volume from the temporary Amazon EC2 instance. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS root volume to be detached from the temporary Amazon EC2 instance. -
aws:executeAwsApi
Detaches the Amazon EBS root volume from the temporary Amazon EC2 instance after an error. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS root volume to be detached from the temporary Amazon EC2 instance after an error. -
aws:branch
Branches the automation depending on whether a snapshot of the root volume was requested to determine the recovery path in case of an error. -
aws:executeAwsApi
Reattaches the root Amazon EBS volume to the target Amazon EC2 instance. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS root volume to be attached to the Amazon EC2 instance. -
aws:executeAwsApi
Creates a new Amazon EBS volume from the target Amazon EC2 instance root volume snapshot. -
aws:waitForAwsResourceProperty
Waits until the new Amazon EBS volume is in anavailable
state. -
aws:executeAwsApi
Attaches the new Amazon EBS volume to the target instance as the root volume. -
aws:waitForAwsResourceProperty
Waits for the Amazon EBS volume to be in anattached
state. -
aws:executeAwsApi
Describes the Amazon CloudFormation stack events if the runbooks fails to create or update the Amazon CloudFormation stack. -
aws:branch
Branches the automation depending on the previous Amazon EC2 instance state. If the state wasrunning
, the instance is started. If it was in astopped
state, the automation continues. -
aws:changeInstanceState
Starts the Amazon EC2 instance if needed. -
aws:waitForAwsResourceProperty
Waits until the Amazon CloudFormation stack is in a terminal status before deleting. -
aws:executeAwsApi
Deletes the Amazon CloudFormation stack including the temporary Amazon EC2 instance.