How can I use the AWSSupport-ResetLinuxUserPassword runbook to change a Linux user password on my EC2 instance?

Short description

The AWSSupport-ResetLinuxUserPassword automation runbook changes the local Operating System (OS) user password. This runbook creates the following resources:

• A temporary Amazon EC2 instance in your AWS account.
• An AWS Identity and Access Management (IAM) role with permissions to retrieve an AWS Secrets Manager secret value containing the password.

Resolution

Prerequisites

• Make sure that the IAM user or role that you're using has the correct permissions.
• Create a Secrets Manager secret for the password that you want to assign to your OS user. The value must be in plaintext. For more information, see Create an AWS Secrets Manager secret.
• (Target EC2 instances with Amazon Elastic Block Store (Amazon EBS) volumes attached only.) Determine if the attached EBS volumes are encrypted with a customer managed AWS Key Management Service (AWS KMS) key. If so, then make sure that the AWS KMS key isn't deleted or turned off. If the AWS KMS key is deleted or turned off, then your instance won't start.

Note:

• It's a best practice to back up your instance before using this runbook. Set the value of the CreateSnapshot parameter to Yes. For more information, see Create Amazon EBS snapshots.
• This runbook stops 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, see Stop and start your instance.

Run the Systems Manager automation runbook

1. Open the AWS Systems Manager console.

2. In the navigation pane, choose Documents.

3. In the search bar, enter AWSSupport-ResetLinuxUserPassword.

4. Select the AWSSupport-ResetLinuxUserPassword document, and then choose Execute automation. Or, choose Run this automation (console).

5. For the input parameters, enter the following:

6. AutomationAssumeRole (optional): Enter the ARN of the IAM role that allows Automation to perform actions on your behalf. If a role isn't specified, then Automation uses the permissions of the user who starts this runbook.

7. InstanceId (required): Enter the ID of the EC2 Linux instance that contains the Linux user password that you want to reset.

8. LinuxUserName (optional): Enter the Linux username of the user whose password you want to reset.
   The default user is ec2-user.

9. SecretArn (required): Enter the ARN of your Secrets Manager secret that contains the new password.

10. SecurityGroupId (optional): Enter the ID of the security group to attach to the temporary EC2 instance. If you don't provide a value for this parameter, then Automation uses the default Amazon Virtual Private Cloud (Amazon VPC) security group.

11. SubnetId (optional): Enter the ID of the subnet that you want to launch the EC2 temporary instance in to. By default, Automation chooses the same subnet as your target instance. If you provide a different subnet, then that subnet must be in the same Availability Zone as the target instance. And, the new subnet must have access to Systems Manager endpoints.

12. CreateSnapshot (optional): To create a snapshot of the root volume of your target EC2 instance, set this option to Yes. The default selection is Yes.

13. StopConsent (required): To acknowledge that Automation stops your target EC2 instance during this runbook, enter Yes. When the 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.
    The default selection is No. If No is entered, then Automation doesn't start the runbook.

14. Choose Execute.

To see detailed results after the runbook completes, review the Outputs section.

Related information

Run an automation

Setting up automation

Systems Manager Automation runbook reference