"`, it means that the signature has successfully been verified, and you can proceed to run the EC2Rescue for Linux installation script.
If the output includes the phrase `BAD signature`, check whether you performed the procedure correctly. If you continue to get this response, contact Amazon Web Services and do not run the installation file that you downloaded previously.
The following are details about the warnings that you might see:
+ **WARNING: This key is not certified with a trusted signature\$1 There is no indication that the signature belongs to the owner.** This refers to your personal level of trust in your belief that you possess an authentic public key for EC2Rescue for Linux. In an ideal world, you would visit an Amazon Web Services office and receive the key in person. However, more often you download it from a website. In this case, the website is an Amazon Web Services website.
+ **gpg2: no ultimately trusted keys found.** This means that the specific key is not "ultimately trusted" by you (or by other people whom you trust).
For more information, see [https://www.gnupg.org/](https://www.gnupg.org/).
# Run EC2Rescue commands on an Amazon EC2 Linux instance
EC2Rescue is a command line tool. After you have installed EC2Rescue on your Linux instance, you can get general help on how to use the tool by running `./ec2rl help`. You can view the available modules by running `./ec2rl list`, and you can get help on a specific module by running `./ec2rl help module_name`.
The following are common tasks you can perform to get started using this tool.
**Topics**
+ [Run EC2Rescue modules](#ec2rl_running_module)
+ [Upload the EC2Rescue module results](#ec2rl_uploading_results)
+ [Create backups of an Amazon EC2 Linux instance](#ec2rl_creating_backups)
## Run EC2Rescue modules
**To run all EC2Rescue modules**
Use the **./ec2rl run** command without specifying any additional parameters. Some modules require root access. If you are not a root user, use **sudo** when you run the command.
```
./ec2rl run
```
**To run a specific EC2Rescue module**
Use the **./ec2rl run** command and for `--only-modules`, specify the name of the module to run. Some modules require *arguments* to use them.
```
./ec2rl run --only-modules=module_name --arguments
```
For example, to run the **dig** module to query the `amazon.com` domain, use the following command.
```
./ec2rl run --only-modules=dig --domain=amazon.com
```
**To view the results of an EC2Rescue module**
Run the module then view the log file in `cat /var/tmp/ec2rl/logfile_location`. For example, the log file for the **dig** module can be found in the following location:
```
cat /var/tmp/ec2rl/timestamp/mod_out/run/dig.log
```
## Upload the EC2Rescue module results
If Support has requested the results for a EC2Rescue module, you can upload the log file using the EC2Rescue tool. You can upload the results either to a location provided by Support or to an Amazon S3 bucket that you own.
**To upload results to a location provided by Support**
Use the **./ec2rl upload** command. For `--upload-directory`, specify the location of the log file. For `--support-url`, specify the URL provided by Support.
```
./ec2rl upload --upload-directory=/var/tmp/ec2rl/logfile_location --support-url="url_provided_by_aws_support"
```
**To upload results to an Amazon S3 bucket**
Use the **./ec2rl upload** command. For `--upload-directory`, specify the location of the log file. For `--presigned-url`, specify a presigned URL for the S3 bucket. For more information about generating pre-signed URLs for Amazon S3, see [Uploading Objects Using Pre-Signed URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html).
```
./ec2rl upload --upload-directory=/var/tmp/ec2rl/logfile_location --presigned-url="presigned_s3_url"
```
## Create backups of an Amazon EC2 Linux instance
You can use EC2Rescue to backup your Linux instance by creating an AMI or by creating snapshots of it's attached volumes.
**To create an AMI**
Use the `./ec2rl run` command and for --`backup`, specify `ami`.
```
./ec2rl run --backup=ami
```
**To create multi-volume snapshots of all attached volumes**
Use the `./ec2rl run` command and for --`backup`, specify `allvolumes`.
```
./ec2rl run --backup=allvolumes
```
**To create a snapshot of a specific attached volume**
Use the `./ec2rl run` command and for --`backup`, specify the ID of the volume to back up.
```
./ec2rl run --backup=vol-01234567890abcdef
```
# Develop EC2Rescue modules for Amazon EC2 Linux instances
Modules are written in YAML, a data serialization standard. A module's YAML file consists of a single document, representing the module and its attributes.
## Add module attributes
The following table lists the available module attributes.
| Attribute | Description |
| --- | --- |
| name | The name of the module. The name should be less than or equal to 18 characters in length. |
| version | The version number of the module. |
| title | A short, descriptive title for the module. This value should be less than or equal to 50 characters in length. |
| helptext | The extended description of the module. Each line should be less than or equal to 75 characters in length. If the module consumes arguments, required or optional, include them in the helptext value. For example: helptext: !!str |
Collect output from ps for system analysis
Consumes --times= for number of times to repeat
Consumes --period= for time period between repetition
|
| placement | The stage in which the module should be run. Supported values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| language | The language that the module code is written in. Supported values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) Python code must be compatible with both Python 2.7.9\$1 and Python 3.2\$1. |
| remediation | Indicates whether the module supports remediation. Supported values are `True` or `False`. The module defaults to `False` if this is absent, making it an optional attribute for those modules that do not support remediation. |
| content | The entirety of the script code. |
| constraint | The name of the object containing the constraint values. |
| domain | A descriptor of how the module is grouped or classified. The set of included modules uses the following domains: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| class | A descriptor of the type of task performed by the module. The set of included modules uses the following classes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| distro | The list of Linux distributions that this module supports. The set of included modules uses the following distributions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| required | The required arguments that the module is consuming from the CLI options. |
| optional | The optional arguments that the module can use. |
| software | The software executables used in the module. This attribute is intended to specify software that is not installed by default. The EC2Rescue for Linux logic ensures that these programs are present and executable before running the module. |
| package | The source software package for an executable. This attribute is intended to provide extended details on the package with the software, including a URL for downloading or getting further information. |
| sudo | Indicates whether root access is required to run the module. You do not need to implement sudo checks in the module script. If the value is true, then the EC2Rescue for Linux logic only runs the module when the executing user has root access. |
| perfimpact | Indicates whether the module can have significant performance impact upon the environment in which it is run. If the value is true and the `--perfimpact=true` argument is not present, then the module is skipped. |
| parallelexclusive | Specifies a program that requires mutual exclusivity. For example, all modules specifying "bpf" run in a serial manner. |
## Add environment variables
The following table lists the available environment variables.
| Environment Variable | Description |
| --- | --- |
| `EC2RL_CALLPATH` | The path to ec2rl.py. This path can be used to locate the lib directory and use vendored Python modules. |
| `EC2RL_WORKDIR` | The main tmp directory for the diagnostic tool. Default value: `/var/tmp/ec2rl`. |
| `EC2RL_RUNDIR` | The directory where all output is stored. Default value: `/var/tmp/ec2rl/`. |
| `EC2RL_GATHEREDDIR` | The root directory for placing gathered module data. Default value:`/var/tmp/ec2rl//mod_out/gathered/`. |
| `EC2RL_NET_DRIVER` | The driver in use for the first, alphabetically ordered, non-virtual network interface on the instance. Examples: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| `EC2RL_SUDO` | True if EC2Rescue for Linux is running as root; otherwise, false. |
| `EC2RL_VIRT_TYPE` | The virtualization type as provided by the instance metadata. Examples: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) |
| `EC2RL_INTERFACES` | An enumerated list of interfaces on the system. The value is a string containing names, such as `eth0`, `eth1`, etc. This is generated via the `functions.bash` and is only available for modules that have sourced it. |
## Use YAML syntax
The following should be noted when constructing your module YAML files:
+ The triple hyphen (`---`) denotes the explicit start of a document.
+ The `!ec2rlcore.module.Module` tag tells the YAML parser which constructor to call when creating the object from the data stream. You can find the constructor inside the `module.py` file.
+ The `!!str` tag tells the YAML parser to not attempt to determine the type of data, and instead interpret the content as a string literal.
+ The pipe character (`|`) tells the YAML parser that the value is a literal-style scalar. In this case, the parser includes all whitespace. This is important for modules because indentation and newline characters are kept.
+ The YAML standard indent is two spaces, which can be seen in the following examples. Ensure that you maintain standard indentation (for example, four spaces for Python) for your script and then indent the entire content two spaces inside the module file.
## Example modules
Example one (`mod.d/ps.yaml`):
```
--- !ec2rlcore.module.Module
# Module document. Translates directly into an almost-complete Module object
name: !!str ps
path: !!str
version: !!str 1.0
title: !!str Collect output from ps for system analysis
helptext: !!str |
Collect output from ps for system analysis
Requires --times= for number of times to repeat
Requires --period= for time period between repetition
placement: !!str run
package:
- !!str
language: !!str bash
content: !!str |
#!/bin/bash
error_trap()
{
printf "%0.s=" {1..80}
echo -e "\nERROR: "$BASH_COMMAND" exited with an error on line ${BASH_LINENO[0]}"
exit 0
}
trap error_trap ERR
# read-in shared function
source functions.bash
echo "I will collect ps output from this $EC2RL_DISTRO box for $times times every $period seconds."
for i in $(seq 1 $times); do
ps auxww
sleep $period
done
constraint:
requires_ec2: !!str False
domain: !!str performance
class: !!str collect
distro: !!str alami ubuntu rhel suse
required: !!str period times
optional: !!str
software: !!str
sudo: !!str False
perfimpact: !!str False
parallelexclusive: !!str
```
# Troubleshoot impaired Amazon EC2 Windows instance using EC2Rescue
EC2Rescue for Windows Server is an easy-to-use tool that you run on an Amazon EC2 Windows Server instance to diagnose and troubleshoot possible problems. It is valuable for collecting log files and troubleshooting issues and also proactively searching for possible areas of concern. It can even examine Amazon EBS root volumes from other instances and collect relevant logs for troubleshooting Windows Server instances using that volume. The following are some common issues that EC2Rescue can address:
+ Instance connectivity issues due to firewall, Remote Desktop Protocol (RDP), or network interface configuration
+ Operating system boot issues due to a stop error, boot loop, or corrupted registry
+ Issues that might need advanced log analysis and troubleshooting
EC2Rescue for Windows Server has two different modules:
+ A **data collector module** that collects data from all different sources
+ An **analyzer module** that parses the data collected against a series of predefined rules to identify issues and provide suggestions
The EC2Rescue for Windows Server tool only runs on Amazon EC2 instances running Windows Server 2012 and later. When the tool starts, it checks whether it is running on an Amazon EC2 instance.
**Note**
The `AWSSupport-ExecuteEC2Rescue` AWS Systems Manager Automation runbook uses the EC2Rescue tool to troubleshoot and, where possible, fix common connectivity issues with the specified EC2 instance. For more information, and to run this automation, see [ >AWSSupport-ExecuteEC2Rescue](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-executeec2rescue.html).
If you are using a Linux instance, see [Troubleshoot impaired Amazon EC2 Linux instance using EC2Rescue](Linux-Server-EC2Rescue.md).
**Topics**
+ [Troubleshoot using EC2Rescue GUI](ec2rw-gui.md)
+ [Troubleshoot using EC2Rescue CLI](ec2rw-cli.md)
+ [Troubleshoot using EC2Rescue and Systems Manager](ec2rw-ssm.md)
# Troubleshoot impaired Windows instance with the EC2Rescue GUI
EC2Rescue for Windows Server can perform the following analysis on ** offline instances**:
| Option | Description |
| --- | --- |
| Diagnose and Rescue | EC2Rescue for Windows Server can detect and address issues with the following service settings: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) |
| Restore | Perform one of the following actions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-gui.html) |
| Capture Logs | Allows you to capture logs on the instance for analysis. |
EC2Rescue for Windows Server can collect the following data from **active and offline instances**:
| Item | Description |
| --- | --- |
| Event Log | Collects application, system, and EC2Config event logs. |
| Registry | Collects SYSTEM and SOFTWARE hives. |
| Windows Update Log | Collects log files generated by Windows Update. In Windows Server 2016 and later, the log is collected in Event Tracing for Windows (ETW) format. |
| Sysprep Log | Collects log files generated by the Windows System Preparation tool. |
| Driver Setup Log | Collects Windows SetupAPI logs (setupapi.dev.log and setupapi.setup.log). |
| Boot Configuration | Collects HKEY\$1LOCAL\$1MACHINE\$1BCD00000000 hive. |
| Memory Dump | Collects any memory dump files that exist on the instance. |
| EC2Config File | Collects log files generated by the EC2Config service. |
| EC2Launch File | Collects log files generated by the EC2Launch scripts. |
| SSM Agent File | Collects log files generated by SSM Agent and Patch Manager logs. |
| EC2 ElasticGPUs File | Collects event logs related to elastic GPUs. |
| ECS | Collects logs related to Amazon ECS. |
| CloudEndure | Collects log files related to CloudEndure Agent. |
| AWS Replication Agent for MGN or DRS Log Files | Collects log files related to AWS Application Migration Service or AWS Elastic Disaster Recovery. |
EC2Rescue for Windows Server can collect the following additional data from **active instances**:
| Item | Description |
| --- | --- |
| System Information | Collects MSInfo32. |
| Group Policy Result | Collects a Group Policy report. |
## Analyze an offline instance
The **Offline Instance** option is useful for debugging boot issues with Windows instances.
**To perform an action on an offline instance**
1. From a working Windows Server instance, download the [EC2Rescue for Windows Server](https://s3.amazonaws.com/ec2rescue/windows/EC2Rescue_latest.zip?x-download-source=docs) tool and extract the files.
You can run the following PowerShell command to download EC2Rescue without changing your Internet Explorer Enhanced Security Configuration (ESC):
```
Invoke-WebRequest https://s3.amazonaws.com/ec2rescue/windows/EC2Rescue_latest.zip -OutFile $env:USERPROFILE\Desktop\EC2Rescue_latest.zip
```
This command will download the EC2Rescue .zip file to the desktop of the currently logged in user.
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016 or earlier, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
1. Stop the faulty instance, if it is not stopped already.
1. Detach the EBS root volume from the faulty instance and attach the volume to a working Windows instance that has EC2Rescue for Windows Server installed.
1. Run the EC2Rescue for Windows Server tool on the working instance and choose **Offline Instance**.
1. Select the disk of the newly mounted volume and choose **Next**.
1. Confirm the disk selection and choose **Yes**.
1. Choose the offline instance option to perform and choose **Next**.
The EC2Rescue for Windows Server tool scans the volume and collects troubleshooting information based on the selected log files.
## Collect data from an active instance
You can collect logs and other data from an active instance.
**To collect data from an active instance**
1. Connect to your Windows instance.
1. Download the [EC2Rescue for Windows Server](https://s3.amazonaws.com/ec2rescue/windows/EC2Rescue_latest.zip?x-download-source=docs) tool to your Windows instance and extract the files.
You can run the following PowerShell command to download EC2Rescue without changing your Internet Explorer Enhanced Security Configuration (ESC):
```
Invoke-WebRequest https://s3.amazonaws.com/ec2rescue/windows/EC2Rescue_latest.zip -OutFile $env:USERPROFILE\Desktop\EC2Rescue_latest.zip
```
This command will download the EC2Rescue .zip file to the desktop of the currently logged in user.
**Note**
If you receive an error when downloading the file, and you are using Windows Server 2016 or earlier, TLS 1.2 might need to be enabled for your PowerShell terminal. You can enable TLS 1.2 for the current PowerShell session with the following command and then try again:
```
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```
1. Open the EC2Rescue for Windows Server application and accept the license agreement.
1. Choose **Next**, **Current instance**, **Capture logs**.
1. Select the data items to collect and choose **Collect...**. Read the warning and choose **Yes** to continue.
1. Choose a file name and location for the ZIP file and choose **Save**.
1. After EC2Rescue for Windows Server completes, choose **Open Containing Folder** to view the ZIP file.
1. Choose **Finish**.
# Troubleshoot impaired Windows instance with the EC2Rescue CLI
The EC2Rescue for Windows Server command line interface (CLI) allows you to run an EC2Rescue for Windows Server plugin (referred as an "action") programmatically.
The EC2Rescue for Windows Server tool has two execution modes:
+ **/online**—This allows you to take action on the instance that EC2Rescue for Windows Server is installed on, such as collect log files.
+ **/offline:**—This allows you to take action on the offline root volume that is attached to a separate Amazon EC2 Windows instance, on which you have installed EC2Rescue for Windows Server.
Download the [EC2Rescue for Windows Server](https://s3.amazonaws.com/ec2rescue/windows/EC2Rescue_latest.zip?x-download-source=docs) tool to your Windows instance and extract the files. You can view the help file using the following command:
```
EC2RescueCmd.exe /help
```
EC2Rescue for Windows Server can perform the following actions on an Amazon EC2 Windows instance:
+ [Collect action](#ec2rw-collect)
+ [Rescue action](#ec2rw-rescue)
+ [Restore action](#ec2rw-restore)
## Collect action
**Note**
You can collect all logs, an entire log group, or an individual log within a group.
EC2Rescue for Windows Server can collect the following data from **active and offline instances**.
| Log group | Available logs | Description |
| --- | --- | --- |
| all | | Collects all available logs. |
| eventlog | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects application, system, and EC2Config event logs. |
| memory-dump | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects any memory dump files that exist on the instance. |
| ec2config | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects log files generated by the EC2Config service. |
| ec2launch | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects log files generated by the EC2Launch scripts. |
| ssm-agent | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects log files generated by SSM Agent and Patch Manager logs. |
| sysprep | 'Log Files' | Collects log files generated by the Windows System Preparation tool. |
| driver-setup | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects Windows SetupAPI logs (setupapi.dev.log and setupapi.setup.log). |
| registry | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects SYSTEM and SOFTWARE hives. |
| egpu | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects event logs related to elastic GPUs. |
| boot-config | 'BCDEDIT Output' | Collects HKEY\$1LOCAL\$1MACHINE\$1BCD00000000 hive. |
| windows-update | 'Log Files' | Collects log files generated by Windows Update. In Windows Server 2016 and later, the log is collected in Event Tracing for Windows (ETW) format. |
| cloudendure | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Collects log files related to CloudEndure Agent. |
EC2Rescue for Windows Server can collect the following additional data from **active instances**.
| Log group | Available logs | Description |
| --- | --- | --- |
| system-info | 'MSInfo32 Output' | Collects MSInfo32. |
| gpresult | 'GPResult Output' | Collects a Group Policy report. |
The following are the available options:
+ **/output:** ‐ Required destination file path location to save collected log files in zip format.
+ **/no-offline** ‐ Optional attribute used in offline mode. Does not set the volume offline after completing the action.
+ **/no-fix-signature** ‐ Optional attribute used in offline mode. Does not fix a possible disk signature collision after completing the action.
### Examples
The following are examples using the EC2Rescue for Windows Server CLI.
#### Online mode examples
Collect all available logs:
```
EC2RescueCmd /accepteula /online /collect:all /output:
```
Collect only a specific log group:
```
EC2RescueCmd /accepteula /online /collect:ec2config /output:
```
Collect individual logs within a log group:
```
EC2RescueCmd /accepteula /online /collect:'ec2config.Log Files,driver-setup.SetupAPI Log Files' /output:
```
#### Offline mode examples
Collect all available logs from an EBS volume. The volume is specified by the device\$1id value.
```
EC2RescueCmd /accepteula /offline:xvdf /collect:all /output:
```
Collect only a specific log group:
```
EC2RescueCmd /accepteula /offline:xvdf /collect:ec2config /output:
```
## Rescue action
EC2Rescue for Windows Server can detect and address issues with the following service settings:
| Service group | Available actions | Description |
| --- | --- | --- |
| all | | |
| system-time | 'RealTimeIsUniversal' | System Time[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) |
| firewall | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Windows Firewall [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) |
| rdp | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | Remote Desktop [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) |
| ec2config | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) | EC2Config [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) |
| ec2launch | 'Reset Administrator Password' | Generates a new Windows administrator password. |
| network | 'DHCP Service Startup' | Network Interface [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2rw-cli.html) |
The following are the available options:
+ **/level:** ‐ Optional attribute for the check level that the action should trigger. Allowed values are: `information`, `warning`, `error`, `all`. By default, it is set to `error`.
+ **/check-only** ‐ Optional attribute that generates a report but makes no modifications to the offline volume.
**Note**
If EC2Rescue for Windows Server detects a possible disk signature collision, it corrects the signature after the offline process completes by default, even when you use the `/check-only` option. You must use the `/no-fix-signature` option to prevent the correction.
+ **/no-offline** ‐ Optional attribute that prevents the volume from being set offline after completing the action.
+ **/no-fix-signature** ‐ Optional attribute that does not fix a possible disk signature collision after completing the action.
### Rescue examples
The following are examples using the EC2Rescue for Windows Server CLI. The volume is specified using the device\$1id value.
Attempt to fix all identified issues on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /rescue:all
```
Attempt to fix all issues within a service group on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /rescue:firewall
```
Attempt to fix a specific item within a service group on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /rescue:rdp.'Service Start'
```
Specify multiple issues to attempt to fix on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /rescue:'system-time.RealTimeIsUniversal,ec2config.Service Start'
```
## Restore action
EC2Rescue for Windows Server can detect and address issues with the following service settings:
| Service Group | Available Actions | Description |
| --- | --- | --- |
| Restore Last Known Good Configuration | lkgc | Last Known Good Configuration ‐ Attempts to boot the instance into the last known bootable state. |
| Restore Windows registry from latest backup | regback | Restore registry from backup ‐ Restores the registry from \$1Windows\$1System32\$1config\$1RegBack. |
The following are the available options:
+ **/no-offline**—Optional attribute that prevents the volume from being set offline after completing the action.
+ **/no-fix-signature**—Optional attribute that does not fix a possible disk signature collision after completing the action.
### Restore examples
The following are examples using the EC2Rescue for Windows Server CLI. The volume is specified using the device\$1id value.
Restore last known good configuration on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /restore:lkgc
```
Restore the last Windows registry backup on a volume:
```
EC2RescueCmd /accepteula /offline:xvdf /restore:regback
```
# Troubleshoot impaired Windows instance with EC2Rescue and Systems Manager
Support provides you with a Systems Manager Run Command document to interface with your Systems Manager-enabled instance to run EC2Rescue for Windows Server. The Run Command document is called `AWSSupport-RunEC2RescueForWindowsTool`.
This Systems Manager Run Command document performs the following tasks:
+ Downloads and verifies EC2Rescue for Windows Server.
+ Imports a PowerShell module to ease your interaction with the tool.
+ Runs EC2RescueCmd with the provided command and parameters.
The Systems Manager Run Command document accepts three parameters:
+ **Command**—The EC2Rescue for Windows Server action. The current allowed values are:
+ **ResetAccess**—Resets the local Administrator password. The local Administrator password of the current instance will be reset and the randomly generated password will be securely stored in Parameter Store as `/EC2Rescue/Password/`. If you select this action and provide no parameters, passwords are encrypted automatically with the default KMS key. Optionally, you can specify a KMS key ID in Parameters to encrypt the password with your own key.
+ **CollectLogs**—Runs EC2Rescue for Windows Server with the `/collect:all` action. If you select this action, `Parameters` must include an Amazon S3 bucket name to upload the logs to.
+ **FixAll**—Runs EC2Rescue for Windows Server with the `/rescue:all` action. If you select this action, `Parameters` must include the block device name to rescue.
+ **Parameters**—The PowerShell parameters to pass for the specified command.
## Requirements
To run the **ResetAccess** action, your Amazon EC2 instance must have the a policy attached that grants permissions to write the encrypted password to Parameter Store. After attaching the policy, wait a few minutes before attempting to reset the password of an instance after you have attached this policy to the related IAM role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:parameter/EC2Rescue/Passwords/"
]
}
]
}
```
------
If you are using a custom KMS key, not the default KMS key, use this policy instead.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:parameter/EC2Rescue/Passwords/"
]
},
{
"Effect": "Allow",
"Action": [
"kms:Encrypt"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/"
]
}
]
}
```
------
## View the JSON for the document
The following procedure describes how to view the JSON for this document.
**To view the JSON for the Systems Manager Run Command document**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, expand **Change Management Tools** and choose **Documents**.
1. In the search bar, enter `AWSSupport-RunEC2RescueForWindowsTool`, and then select the `AWSSupport-RunEC2RescueForWindowsTool` document.
1. Choose the **Content** tab.
## Examples
Here are some examples on how to use the Systems Manager Run Command document to run EC2Rescue for Windows Server, using the AWS CLI. For more information about sending commands using the AWS CLI, see [send-command](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html).
**Topics**
+ [Attempt to fix all identified issues on an offline root volume](#ec2rw-ssm-exam1)
+ [Collect logs from the current Amazon EC2 Windows instance](#ec2rw-ssm-exam2)
+ [Reset the local Administrator password](#ec2rw-ssm-exam4)
### Attempt to fix all identified issues on an offline root volume
Attempt to fix all identified issues on an offline root volume attached to an Amazon EC2 Windows instance:
```
aws ssm send-command --instance-ids "i-0cb2b964d3e14fd9f" --document-name "AWSSupport-RunEC2RescueForWindowsTool" --parameters "Command=FixAll, Parameters='xvdf'" --output text
```
### Collect logs from the current Amazon EC2 Windows instance
Collect all logs from the current online Amazon EC2 Windows instance and upload them to an Amazon S3 bucket:
```
aws ssm send-command --instance-ids "i-0cb2b964d3e14fd9f" --document-name "AWSSupport-RunEC2RescueForWindowsTool" --parameters "Command=CollectLogs, Parameters='amzn-s3-demo-bucket'" --output text
```
### Reset the local Administrator password
The following examples show methods you can use to reset the local Administrator password. The output provides a link to Parameter Store, where you can find the randomly generated secure password you can then use to RDP to your Amazon EC2 Windows instance as the local Administrator.
Reset the local Administrator password of an online instance using the default AWS KMS key alias/aws/ssm:
```
aws ssm send-command --instance-ids "i-0cb2b964d3e14fd9f" --document-name "AWSSupport-RunEC2RescueForWindowsTool" --parameters "Command=ResetAccess" --output text
```
Reset the local Administrator password of an online instance using a KMS key:
```
aws ssm send-command --instance-ids "i-0cb2b964d3e14fd9f" --document-name "AWSSupport-RunEC2RescueForWindowsTool" --parameters "Command=ResetAccess, Parameters=a133dc3c-a2g4-4fc6-a873-6c0720104bf0" --output text
```
**Note**
In this example, the KMS key is `a133dc3c-a2g4-4fc6-a873-6c0720104bf0`.
# EC2 Serial Console for instances
With the EC2 serial console, you have access to your Amazon EC2 instance's serial port, which you can use to troubleshoot boot, network configuration, and other issues. The serial console does not require your instance to have any networking capabilities. With the serial console, you can enter commands to an instance as if your keyboard and monitor are directly attached to the instance's serial port. The serial console session lasts during instance reboot and stop. During reboot, you can view all of the boot messages from the start.
Access to the serial console is not available by default. Your organization must grant account access to the serial console and configure IAM policies to grant your users access to the serial console. Serial console access can be controlled at a granular level by using instance IDs, resource tags, and other IAM levers. For more information, see [Configure access to the EC2 Serial Console](configure-access-to-serial-console.md).
The serial console can be accessed by using the EC2 console or the AWS CLI.
The serial console is available at no additional cost.
**Topics**
+ [Prerequisites for the EC2 Serial Console](ec2-serial-console-prerequisites.md)
+ [Configure access to the EC2 Serial Console](configure-access-to-serial-console.md)
+ [Connect to the EC2 Serial Console](connect-to-serial-console.md)
+ [Disconnect from the EC2 Serial Console](disconnect-serial-console-session.md)
+ [Troubleshoot your Amazon EC2 instance using the EC2 Serial Console](troubleshoot-using-serial-console.md)
# Prerequisites for the EC2 Serial Console
**Topics**
+ [AWS Regions](#sc-prereqs-regions)
+ [Wavelength Zones and AWS Outposts](#sc-prereqs-wavelength-zones-outposts)
+ [Local Zones](#sc-prereqs-local-zones)
+ [Instance types](#sc-prereqs-instance-types)
+ [Grant access](#sc-prereqs-configure-ec2-serial-console)
+ [Support for browser-based client](#sc-prereqs-for-browser-based-connection)
+ [Instance state](#sc-prereqs-instance-state)
+ [Amazon EC2 Systems Manager](#sc-prereqs-ssm)
+ [Configure your chosen troubleshooting tool](#sc-prereqs-configure-troubleshooting-tool)
## AWS Regions
Supported in all AWS Regions.
## Wavelength Zones and AWS Outposts
Not supported.
## Local Zones
Supported in all Local Zones.
## Instance types
Supported instance types:
+ **Linux**
+ All virtualized instances built on the Nitro System.
+ All bare metal instances except:
+ General purpose: `a1.metal`, `mac1.metal`, `mac2.metal`
+ Accelerated computing: `g5g.metal`
+ Memory optimized: `u-6tb1.metal`, `u-9tb1.metal`, `u-12tb1.metal`, `u-18tb1.metal`, `u-24tb1.metal`
+ **Windows**
All virtualized instances built on the Nitro System. Not supported on bare metal instances.
## Grant access
You must complete the configuration tasks to grant access to the EC2 Serial Console. For more information, see [Configure access to the EC2 Serial Console](configure-access-to-serial-console.md).
## Support for browser-based client
To connect to the serial console [using the browser-based client](connect-to-serial-console.md#sc-connect-browser-based-client), your browser must support WebSocket. If your browser does not support WebSocket, connect to the serial console [using your own key and an SSH client.](connect-to-serial-console.md#sc-connect-SSH)
## Instance state
Must be `running`.
You can't connect to the serial console if the instance is in the `pending`, `stopping`, `stopped`, `shutting-down`, or `terminated` state.
For more information about the instance states, see [Amazon EC2 instance state changes](ec2-instance-lifecycle.md).
## Amazon EC2 Systems Manager
If the instance uses Amazon EC2 Systems Manager, then SSM Agent version 3.0.854.0 or later must be installed on the instance. For information about SSM Agent, see [Working with SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) in the *AWS Systems Manager User Guide*.
## Configure your chosen troubleshooting tool
To troubleshoot your instance using the serial console, you can use GRUB or SysRq on Linux instances, and Special Admin Console (SAC) on Windows instances. Before you can use these tools, you must first perform configuration steps on every instance on which you'll use them.
Use the instructions for your instance's operating system to configure your chosen troubleshooting tool.
### (Linux instances) Configure GRUB
To configure GRUB, choose one of the following procedures based on the AMI that was used to launch the instance.
------
#### [ Amazon Linux 2 ]
**To configure GRUB on an Amazon Linux 2 instance**
1. [Connect to your Linux instance using SSH](connect-to-linux-instance.md)
1. Add or change the following options in `/etc/default/grub`:
+ Set `GRUB_TIMEOUT=1`.
+ Add `GRUB_TERMINAL="console serial"`.
+ Add `GRUB_SERIAL_COMMAND="serial --speed=115200"`.
The following is an example of `/etc/default/grub`. You might need to change the configuration based on your system setup.
```
GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8 net.ifnames=0 biosdevname=0 nvme_core.io_timeout=4294967295 rd.emergency=poweroff rd.shell=0"
GRUB_TIMEOUT=1
GRUB_DISABLE_RECOVERY="true"
GRUB_TERMINAL="console serial"
GRUB_SERIAL_COMMAND="serial --speed=115200"
```
1. Apply the updated configuration by running the following command.
```
[ec2-user ~]$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```
------
#### [ Ubuntu ]
**To configure GRUB on an Ubuntu instance**
1. [Connect](connect-to-linux-instance.md) to your instance.
1. Add or change the following options in `/etc/default/grub.d/50-cloudimg-settings.cfg`:
+ Set `GRUB_TIMEOUT=1`.
+ Add `GRUB_TIMEOUT_STYLE=menu`.
+ Add `GRUB_TERMINAL="console serial"`.
+ Remove `GRUB_HIDDEN_TIMEOUT`.
+ Add `GRUB_SERIAL_COMMAND="serial --speed=115200"`.
The following is an example of `/etc/default/grub.d/50-cloudimg-settings.cfg`. You might need to change the configuration based on your system setup.
```
# Cloud Image specific Grub settings for Generic Cloud Images
# CLOUD_IMG: This file was created/modified by the Cloud Image build process
# Set the recordfail timeout
GRUB_RECORDFAIL_TIMEOUT=0
# Do not wait on grub prompt
GRUB_TIMEOUT=1
GRUB_TIMEOUT_STYLE=menu
# Set the default commandline
GRUB_CMDLINE_LINUX_DEFAULT="console=tty1 console=ttyS0 nvme_core.io_timeout=4294967295"
# Set the grub console type
GRUB_TERMINAL="console serial"
GRUB_SERIAL_COMMAND="serial --speed 115200"
```
1. Apply the updated configuration by running the following command.
```
[ec2-user ~]$ sudo update-grub
```
------
#### [ RHEL ]
**To configure GRUB on a RHEL instance**
1. [Connect](connect-to-linux-instance.md) to your instance.
1. Add or change the following options in `/etc/default/grub`:
+ Remove `GRUB_TERMINAL_OUTPUT`.
+ Add `GRUB_TERMINAL="console serial"`.
+ Add `GRUB_SERIAL_COMMAND="serial --speed=115200"`.
The following is an example of `/etc/default/grub`. You might need to change the configuration based on your system setup.
```
GRUB_TIMEOUT=1
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_DISABLE_SUBMENU=true
GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,115200n8 net.ifnames=0 rd.blacklist=nouveau nvme_core.io_timeout=4294967295 crashkernel=auto"
GRUB_DISABLE_RECOVERY="true"
GRUB_ENABLE_BLSCFG=true
GRUB_TERMINAL="console serial"
GRUB_SERIAL_COMMAND="serial --speed=115200"
```
1. Apply the updated configuration by running the following command.
```
[ec2-user ~]$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg --update-bls-cmdline
```
For RHEL 9.2 and earlier, use the following command.
```
[ec2-user ~]$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```
------
#### [ CentOS ]
For instances that are launched using a CentOS AMI, GRUB is configured for the serial console by default.
The following is an example of `/etc/default/grub`. Your configuration might be different based on your system setup.
```
GRUB_TIMEOUT=1
GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"
GRUB_DEFAULT=saved
GRUB_DISABLE_SUBMENU=true
GRUB_TERMINAL="serial console"
GRUB_SERIAL_COMMAND="serial --speed=115200"
GRUB_CMDLINE_LINUX="console=tty0 crashkernel=auto console=ttyS0,115200"
GRUB_DISABLE_RECOVERY="true"
```
------
### (Linux instances) Configure SysRq
To configure SysRq, you enable the SysRq commands for the current boot cycle. To make the configuration persistent, you can also enable the SysRq commands for subsequent boots.
**To enable all SysRq commands for the current boot cycle**
1. [Connect](connect-to-linux-instance.md) to your instance.
1. Run the following command.
```
[ec2-user ~]$ sudo sysctl -w kernel.sysrq=1
```
This setting will clear on the next reboot.
**To enable all SysRq commands for subsequent boots**
1. Create the file `/etc/sysctl.d/99-sysrq.conf` and open it in your favorite editor.
```
[ec2-user ~]$ sudo vi /etc/sysctl.d/99-sysrq.conf
```
1. Add the following line.
```
kernel.sysrq=1
```
1. Reboot the instance to apply the changes.
```
[ec2-user ~]$ sudo reboot
```
1. At the `login` prompt, enter the username of the password-based user that you [set up previously](configure-access-to-serial-console.md#set-user-password), and then press **Enter**.
1. At the `Password` prompt, enter the password, and then press **Enter**.
### (Windows instances) Enable SAC and the boot menu
**Note**
If you enable SAC on an instance, the EC2 services that rely on password retrieval will not work from the Amazon EC2 console. Windows on Amazon EC2 launch agents (EC2Config, EC2Launch v1, and EC2Launch v2) rely on the serial console to execute various tasks. These tasks do not perform successfully when you enable SAC on an instance. For more information about Windows on Amazon EC2 launch agents, see [Configure your Amazon EC2 Windows instance](ec2-windows-instances.md). If you enable SAC, you can disable it later. For more information, see [Disable SAC and the boot menu](troubleshoot-using-serial-console.md#disable-sac-bootmenu).
Use one of the following methods to enable SAC and the boot menu on an instance.
------
#### [ PowerShell ]
**To enable SAC and the boot menu on a Windows instance**
1. [Connect](connecting_to_windows_instance.md) to your instance and perform the following steps from an elevated PowerShell command line.
1. Enable SAC.
```
bcdedit /ems '{current}' on
bcdedit /emssettings EMSPORT:1 EMSBAUDRATE:115200
```
1. Enable the boot menu.
```
bcdedit /set '{bootmgr}' displaybootmenu yes
bcdedit /set '{bootmgr}' timeout 15
bcdedit /set '{bootmgr}' bootems yes
```
1. Apply the updated configuration by rebooting the instance.
```
shutdown -r -t 0
```
------
#### [ Command prompt ]
**To enable SAC and the boot menu on a Windows instance**
1. [Connect](connecting_to_windows_instance.md) to your instance and perform the following steps from the command prompt.
1. Enable SAC.
```
bcdedit /ems {current} on
bcdedit /emssettings EMSPORT:1 EMSBAUDRATE:115200
```
1. Enable the boot menu.
```
bcdedit /set {bootmgr} displaybootmenu yes
bcdedit /set {bootmgr} timeout 15
bcdedit /set {bootmgr} bootems yes
```
1. Apply the updated configuration by rebooting the instance.
```
shutdown -r -t 0
```
------
# Configure access to the EC2 Serial Console
To configure access to the serial console, you must grant serial console access at the account level and then configure IAM policies to grant access to your users. For Linux instances you must also configure a password-based user on every instance so that your users can use the serial console for troubleshooting.
EC2 Serial Console uses a virtual serial port connection to interact with an instance. This connection is independent of the instance VPC, so that you can work with the instance operating system and run troubleshooting tools even if there are boot failures or network configuration issues. Because this connection is outside of the VPC network, EC2 Serial Console does not use the instance security group or the subnet network ACL to authorize traffic to the instance.
**Before you begin**
Verify that the [prerequisites](ec2-serial-console-prerequisites.md) are met.
**Topics**
+ [Levels of access to the EC2 Serial Console](#serial-console-access-levels)
+ [Manage account access to the EC2 Serial Console](#serial-console-account-access)
+ [Configure IAM policies for EC2 Serial Console access](#serial-console-iam)
+ [Set an OS user password on a Linux instance](#set-user-password)
## Levels of access to the EC2 Serial Console
By default, there is no access to the serial console at the account level. You need to explicitly grant access to the serial console at the account level. For more information, see [Manage account access to the EC2 Serial Console](#serial-console-account-access).
You can use a service control policy (SCP) to allow access to the serial console within your organization. You can then have granular access control at the user level by using an IAM policy to control access. By using a combination of SCP and IAM policies, you have different levels of access control to the serial console.
**Organization level**
You can use a service control policy (SCP) to allow access to the serial console for member accounts within your organization. For more information about SCPs, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*.
**Instance level**
You can configure the serial console access policies by using IAM PrincipalTag and ResourceTag constructions and by specifying instances by their ID. For more information, see [Configure IAM policies for EC2 Serial Console access](#serial-console-iam).
**User level**
You can configure access at the user level by configuring an IAM policy to allow or deny a specified user the permission to push the SSH public key to the serial console service of a particular instance. For more information, see [Configure IAM policies for EC2 Serial Console access](#serial-console-iam).
**OS level** (Linux instances only)
You can set a user password at the guest OS level. This provides access to the serial console for some use cases. However, to monitor the logs, you don't need a password-based user. For more information, see [Set an OS user password on a Linux instance](#set-user-password).
## Manage account access to the EC2 Serial Console
By default, there is no access to the serial console at the account level. You need to explicitly grant access to the serial console at the account level.
This setting is configured at the account level, either directly in the account or by using a declarative policy. It must be configured in each AWS Region where you want to grant access to the serial console. Using a declarative policy allows you to apply the setting across multiple Regions simultaneously, as well as across multiple accounts simultaneously. When a declarative policy is in use, you can't modify the setting directly within an account. This topic describes how to configure the setting directly within an account. For information about using declarative policies, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide.*
**Contents**
+ [Grant permission to users to manage account access](#sc-account-access-permissions)
+ [View account access status to the serial console](#sc-view-account-access)
+ [Grant account access to the serial console](#sc-grant-account-access)
+ [Deny account access to the serial console](#sc-deny-account-access)
### Grant permission to users to manage account access
To allow your users to manage account access to the EC2 serial console, you need to grant them the required IAM permissions.
The following policy grants permissions to view the account status, and to allow and prevent account access to the EC2 serial console.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:GetSerialConsoleAccessStatus",
"ec2:EnableSerialConsoleAccess",
"ec2:DisableSerialConsoleAccess"
],
"Resource": "*"
}
]
}
```
------
For more information, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
### View account access status to the serial console
------
#### [ Console ]
**To view account access to the serial console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **EC2 Serial Console**.
1. On the **EC2 Serial Console** tab, the value of **EC2 Serial Console access** is either **Allowed** or **Prevented**.
------
#### [ AWS CLI ]
**To view account access to the serial console**
Use the [get-serial-console-access-status](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-serial-console-access-status.html) command.
```
aws ec2 get-serial-console-access-status
```
The following is example output. A value of `true` indicates that the account is allowed access to the serial console.
```
{
"SerialConsoleAccessEnabled": true,
"ManagedBy": "account"
}
```
The `ManagedBy` field indicates the entity that configured the setting. The possible values are `account` (configured directly) or `declarative-policy`. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*.
------
#### [ PowerShell ]
**To view account access to the serial console**
Use the [Get-EC2SerialConsoleAccessStatus](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2SerialConsoleAccessStatus.html) cmdlet.
```
Get-EC2SerialConsoleAccessStatus -Select *
```
The following is example output. A value of `True` indicates that the account is allowed access to the serial console.
```
ManagedBy SerialConsoleAccessEnabled
--------- --------------------------
account True
```
The `ManagedBy` field indicates the entity that configured the setting. The possible values are `account` (configured directly) or `declarative-policy`. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*.
------
### Grant account access to the serial console
------
#### [ Console ]
**To grant account access to the serial console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **EC2 Serial Console**.
1. Choose **Manage**.
1. To allow access to the EC2 serial console of all instances in the account, select the **Allow** checkbox.
1. Choose **Update**.
------
#### [ AWS CLI ]
**To grant account access to the serial console**
Use the [enable-serial-console-access](https://docs.aws.amazon.com/cli/latest/reference/ec2/enable-serial-console-access.html) command.
```
aws ec2 enable-serial-console-access
```
The following is example output.
```
{
"SerialConsoleAccessEnabled": true
}
```
------
#### [ PowerShell ]
**To grant account access to the serial console**
Use the [Enable-EC2SerialConsoleAccess](https://docs.aws.amazon.com/powershell/latest/reference/items/Enable-EC2SerialConsoleAccess.html) cmdlet.
```
Enable-EC2SerialConsoleAccess
```
The following is example output.
```
True
```
------
### Deny account access to the serial console
------
#### [ Console ]
**To deny account access to the serial console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Dashboard**.
1. On the **Account attributes** card, under **Settings**, choose **EC2 Serial Console**.
1. Choose **Manage**.
1. To prevent access to the EC2 serial console of all instances in the account, clear the **Allow** checkbox.
1. Choose **Update**.
------
#### [ AWS CLI ]
**To deny account access to the serial console**
Use the [disable-serial-console-access](https://docs.aws.amazon.com/cli/latest/reference/ec2/disable-serial-console-access.html) command.
```
aws ec2 disable-serial-console-access
```
The following is example output.
```
{
"SerialConsoleAccessEnabled": false
}
```
------
#### [ PowerShell ]
**To deny account access to the serial console**
Use the [Disable-EC2SerialConsoleAccess](https://docs.aws.amazon.com/powershell/latest/reference/items/Disable-EC2SerialConsoleAccess.html) cmdlet.
```
Disable-EC2SerialConsoleAccess
```
The following is example output.
```
False
```
------
## Configure IAM policies for EC2 Serial Console access
By default, your users do not have access to the serial console. Your organization must configure IAM policies to grant your users the required access. For more information, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*.
For serial console access, create a JSON policy document that includes the `ec2-instance-connect:SendSerialConsoleSSHPublicKey` action. This action grants a user permission to push the public key to the serial console service, which starts a serial console session. We recommend restricting access to specific EC2 instances. Otherwise, all users with this permission can connect to the serial console of all EC2 instances.
**Topics**
+ [Explicitly allow access to the serial console](#iam-explicitly-allow-access)
+ [Explicitly deny access to the serial console](#serial-console-IAM-policy)
+ [Use resource tags to control access to the serial console](#iam-resource-tags)
### Explicitly allow access to the serial console
By default, no one has access to the serial console. To grant access to the serial console, you need to configure a policy to explicitly allow access. We recommend configuring a policy that restricts access to specific instances.
The following policy allows access to the serial console of a specific instance, identified by its instance ID.
Note that the `DescribeInstances`, `DescribeInstanceTypes`, and `GetSerialConsoleAccessStatus` actions do not support resource-level permissions, and therefore all resources, indicated by the `*` (asterisk), must be specified for these actions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:GetSerialConsoleAccessStatus"
],
"Resource": "*"
},
{
"Sid": "AllowinstanceBasedSerialConsoleAccess",
"Effect": "Allow",
"Action": [
"ec2-instance-connect:SendSerialConsoleSSHPublicKey"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance/i-0598c7d356eba48d7"
}
]
}
```
------
### Explicitly deny access to the serial console
The following IAM policy allows access to the serial console of all instances, denoted by the `*` (asterisk), and explicitly denies access to the serial console of a specific instance, identified by its ID.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowSerialConsoleAccess",
"Effect": "Allow",
"Action": [
"ec2-instance-connect:SendSerialConsoleSSHPublicKey",
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:GetSerialConsoleAccessStatus"
],
"Resource": "*"
},
{
"Sid": "DenySerialConsoleAccess",
"Effect": "Deny",
"Action": [
"ec2-instance-connect:SendSerialConsoleSSHPublicKey"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance/i-0598c7d356eba48d7"
}
]
}
```
------
### Use resource tags to control access to the serial console
You can use resource tags to control access to the serial console of an instance.
Attribute-based access control is an authorization strategy that defines permissions based on tags that can be attached to users and AWS resources. For example, the following policy allows a user to initiate a serial console connection for an instance only if that instance's resource tag and the principal's tag have the same `SerialConsole` value for the tag key.
For more information about using tags to control access to your AWS resources, see [Controlling access to AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-resources) in the *IAM User Guide*.
Note that the `DescribeInstances`, `DescribeInstanceTypes`, and `GetSerialConsoleAccessStatus` actions do not support resource-level permissions, and therefore all resources, indicated by the `*` (asterisk), must be specified for these actions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowDescribeInstances",
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:GetSerialConsoleAccessStatus"
],
"Resource": "*"
},
{
"Sid": "AllowTagBasedSerialConsoleAccess",
"Effect": "Allow",
"Action": [
"ec2-instance-connect:SendSerialConsoleSSHPublicKey"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:instance/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/SerialConsole": "${aws:PrincipalTag/SerialConsole}"
}
}
}
]
}
```
------
## Set an OS user password on a Linux instance
You can connect to the serial console without a password. However, to *use* the serial console for troubleshooting a Linux instance, the instance must have a password-based OS user.
You can set the password for any OS user, including the root user. Note that the root user can modify all files, while each OS user might have limited permissions.
You must set a user password for every instance for which you will use the serial console. This is a one-time requirement for each instance.
**Note**
By default, AMIs provided by AWS are not configured with a password-based user. If you launched your instance using an AMI that already has the root user password configured, you can skip these instructions.
**To set an OS user password on a Linux instance**
1. [Connect](connect-to-linux-instance.md) to your instance. You can use any method for connecting to your instance, except the EC2 Serial Console connection method.
1. To set the password for a user, use the **passwd** command. In the following example, the user is `root`.
```
[ec2-user ~]$ sudo passwd root
```
The following is example output.
```
Changing password for user root.
New password:
```
1. At the `New password` prompt, enter the new password.
1. At the prompt, re-enter the password.
# Connect to the EC2 Serial Console
You can connect to the serial console of your EC2 instance by using the Amazon EC2 console or through SSH. After connecting to the serial console, you can use it for troubleshooting boot, network configuration, and other issues. For more information about troubleshooting, see [Troubleshoot your Amazon EC2 instance using the EC2 Serial Console](troubleshoot-using-serial-console.md).
**Considerations**
+ Only 1 active serial console connection is supported per instance.
+ The serial console connection typically lasts for 1 hour unless [you disconnect from it](disconnect-serial-console-session.md). However, during system maintenance, Amazon EC2 will disconnect the serial console session.
The duration of the connection is not determined by the duration of your IAM credentials. If your IAM credentials expire, the connection continues to persist until the maximum duration of the serial console connection is reached. When using the EC2 Serial Console console experience, if your IAM credentials expire, terminate the connection by closing the browser page.
+ It takes 30 seconds to tear down a session after you've disconnected from the serial console in order to allow a new session.
+ Supported serial console ports: `ttyS0` (Linux instances) and `COM1` (Windows instances)
+ When you connect to the serial console, you might observe a slight drop in your instance’s throughput.
**Topics**
+ [Connect using the browser-based client](#sc-connect-browser-based-client)
+ [Connect using your own key and SSH client](#sc-connect-SSH)
+ [EC2 Serial Console endpoints and fingerprints](#sc-endpoints-and-fingerprints)
## Connect using the browser-based client
You can connect to your EC2 instance's serial console by using the browser-based client. You do this by selecting the instance in the Amazon EC2 console and choosing to connect to the serial console. The browser-based client handles the permissions and provides a successful connection.
EC2 serial console works from most browsers, and supports keyboard and mouse input.
Before connecting, make sure you have completed the [prerequisites](ec2-serial-console-prerequisites.md).
**To connect to your instance's serial port using the browser-based client (Amazon EC2 console)**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Instances**.
1. Select the instance and choose **Actions**, **Monitor and troubleshoot**, **EC2 Serial Console**, **Connect**.
Alternatively, select the instance and choose **Connect**, **EC2 Serial Console**, **Connect**.
An in-browser terminal window opens.
1. Press **Enter**. If a login prompt returns, you are connected to the serial console.
If the screen remains black, you can use the following information to help resolve issues with connecting to the serial console:
+ **Check that you have configured access to the serial console.** For more information, see [Configure access to the EC2 Serial Console](configure-access-to-serial-console.md).
+ (Linux instances only) **Use SysRq to connect to the serial console.** SysRq does not require that you connect using the browser-based client. For more information, see [(Linux instances) Use SysRq to troubleshoot your instanceSysRq (Linux)](troubleshoot-using-serial-console.md#SysRq).
+ (Linux instances only) **Restart getty.** If you have SSH access to your instance, then connect to your instance using SSH, and restart getty using the following command.
```
[ec2-user ~]$ sudo systemctl restart serial-getty@ttyS0
```
+ **Reboot your instance.** You can reboot your instance by using SysRq (Linux instances), the EC2 console, or the AWS CLI. For more information, see [(Linux instances) Use SysRq to troubleshoot your instanceSysRq (Linux)](troubleshoot-using-serial-console.md#SysRq) (Linux instances) or [Reboot your Amazon EC2 instance](ec2-instance-reboot.md).
1. (Linux instances only) At the `login` prompt, enter the username of the password-based user that you [set up previously](configure-access-to-serial-console.md#set-user-password), and then press **Enter**.
1. (Linux instances only) At the `Password` prompt, enter the password, and then press **Enter**.
## Connect using your own key and SSH client
You can use your own SSH key and connect to your instance from the SSH client of your choice while using the serial console API. This enables you to benefit from the serial console capability to push a public key to the instance.
After pushing the SSH key to the instance, the SSH connection is not subject to the IAM policies that you configured to grant users EC2 Serial Console access.
**Before you begin**
Verify that the [prerequisites](ec2-serial-console-prerequisites.md) are met.
**To connect to an instance's serial console using SSH**
1. **Push your SSH public key to the instance to start a serial console session**
Use the [send-serial-console-ssh-public-key](https://docs.aws.amazon.com/cli/latest/reference/ec2-instance-connect/send-serial-console-ssh-public-key.html) command to push your SSH public key to the instance. This starts a serial console session.
If a serial console session has already been started for this instance, the command fails because you can only have one session open at a time. It takes 30 seconds to tear down a session after you've disconnected from the serial console in order to allow a new session.
```
aws ec2-instance-connect send-serial-console-ssh-public-key \
--instance-id i-001234a4bf70dec41EXAMPLE \
--serial-port 0 \
--ssh-public-key file://my_key.pub \
--region us-east-1
```
1.
**Connect to the serial console using your private key**
Use the **ssh** command to connect to the serial console before the public key is removed from the serial console service. You have 60 seconds before it is removed.
Use the private key that corresponds to the public key.
The username format is `instance-id.port0`, which comprises the instance ID and port 0. In the following example, the username is `i-001234a4bf70dec41EXAMPLE.port0`.
The endpoint of the serial console service is different for each Region. See the [EC2 Serial Console endpoints and fingerprints](#sc-endpoints-and-fingerprints) table for each Region's endpoint. In the following example, the serial console service is in the us-east-1 Region.
```
ssh -i my_key i-001234a4bf70dec41EXAMPLE.port0@serial-console.ec2-instance-connect.us-east-1.aws
```
The following example uses `timeout 3600` to set your SSH session to terminate after 1 hour. Processes started during the session may continue running on your instance after the session terminates.
```
timeout 3600 ssh -i my_key i-001234a4bf70dec41EXAMPLE.port0@serial-console.ec2-instance-connect.us-east-1.aws
```
1.
**(Optional) Verify the fingerprint**
When you connect for the first time to the serial console, you are prompted to verify the fingerprint. You can compare the serial console fingerprint with the fingerprint that's displayed for verification. If these fingerprints don't match, someone might be attempting a "man-in-the-middle" attack. If they match, you can confidently connect to the serial console.
The following fingerprint is for the serial console service in the us-east-1 Region. For the fingerprints for each Region, see [EC2 Serial Console endpoints and fingerprints](#sc-endpoints-and-fingerprints).
```
SHA256:dXwn5ma/xadVMeBZGEru5l2gx+yI5LDiJaLUcz0FMmw
```
The fingerprint only appears the first time you connect to the serial console.
1. Press **Enter**. If a prompt returns, you are connected to the serial console.
If the screen remains black, you can use the following information to help resolve issues with connecting to the serial console:
+ **Check that you have configured access to the serial console.** For more information, see [Configure access to the EC2 Serial Console](configure-access-to-serial-console.md).
+ (Linux instances only) **Use SysRq to connect to the serial console.** SysRq does not require that you connect using SSH. For more information, see [(Linux instances) Use SysRq to troubleshoot your instanceSysRq (Linux)](troubleshoot-using-serial-console.md#SysRq).
+ (Linux instances only) **Restart getty.** If you have SSH access to your instance, then connect to your instance using SSH, and restart getty using the following command.
```
[ec2-user ~]$ sudo systemctl restart serial-getty@ttyS0
```
+ **Reboot your instance.** You can reboot your instance by using SysRq (Linux instances only), the EC2 console, or the AWS CLI. For more information, see [(Linux instances) Use SysRq to troubleshoot your instanceSysRq (Linux)](troubleshoot-using-serial-console.md#SysRq) (Linux instances only) or [Reboot your Amazon EC2 instance](ec2-instance-reboot.md).
1. (Linux instances only) At the `login` prompt, enter the username of the password-based user that you [set up previously](configure-access-to-serial-console.md#set-user-password), and then press **Enter**.
1. (Linux instances only) At the `Password` prompt, enter the password, and then press **Enter**.
## EC2 Serial Console endpoints and fingerprints
The following are the service endpoints and fingerprints for EC2 Serial Console. To connect programmatically to an instance's serial console, you use an EC2 Serial Console endpoint. The EC2 Serial Console endpoints and fingerprints are unique for each AWS Region.
| Region Name | Region | Endpoint | Fingerprint |
| --- | --- | --- | --- |
| US East (Ohio) | us-east-2 | serial-console.ec2-instance-connect.us-east-2.aws | SHA256:EhwPkTzRtTY7TRSzz26XbB0/HvV9jRM7mCZN0xw/d/0 |
| US East (N. Virginia) | us-east-1 | serial-console.ec2-instance-connect.us-east-1.aws | SHA256:dXwn5ma/xadVMeBZGEru5l2gx\$1yI5LDiJaLUcz0FMmw |
| US West (N. California) | us-west-1 | serial-console.ec2-instance-connect.us-west-1.aws | SHA256:OHldlcMET8u7QLSX3jmRTRAPFHVtqbyoLZBMUCqiH3Y |
| US West (Oregon) | us-west-2 | serial-console.ec2-instance-connect.us-west-2.aws | SHA256:EMCIe23TqKaBI6yGHainqZcMwqNkDhhAVHa1O2JxVUc |
| Africa (Cape Town) | af-south-1 | ec2-serial-console.af-south-1.api.aws | SHA256:RMWWZ2fVePeJUqzjO5jL2KIgXsczoHlz21Ed00biiWI |
| Asia Pacific (Hong Kong) | ap-east-1 | ec2-serial-console.ap-east-1.api.aws | SHA256:T0Q1lpiXxChoZHplnAkjbP7tkm2xXViC9bJFsjYnifk |
| Asia Pacific (Taipei) | ap-east-2 | ec2-serial-console.ap-east-2.api.aws | SHA256:z1rsF5DE8aQqsHwBr/D40tR2GnyMqnScCUa1z1eFwDQ |
| Asia Pacific (Hyderabad) | ap-south-2 | ec2-serial-console.ap-south-2.api.aws | SHA256:WJgPBSwV4/shN\$1OPITValoewAuYj15DVW845JEhDKRs |
| Asia Pacific (Jakarta) | ap-southeast-3 | ec2-serial-console.ap-southeast-3.api.aws | SHA256:5ZwgrCh\$1lfns32XITqL/4O0zIfbx4bZgsYFqy3o8mIk |
| Asia Pacific (Malaysia) | ap-southeast-5 | ec2-serial-console.ap-southeast-5.api.aws | SHA256:cQXTHQMRcqRdIjmAGoAMBSExeoRobYyRwT67yTjnEiA |
| Asia Pacific (New Zealand) | ap-southeast-6 | ec2-serial-console.ap-southeast-6.api.aws | SHA256:wNltdH0gVfM5uHJKjrw\$1ElFuKoJgalcSKqjCS\$1lLkv4 |
| Asia Pacific (Melbourne) | ap-southeast-4 | ec2-serial-console.ap-southeast-4.api.aws | SHA256:Avaq27hFgLvjn5gTSShZ0oV7h90p0GG46wfOeT6ZJvM |
| Asia Pacific (Mumbai) | ap-south-1 | serial-console.ec2-instance-connect.ap-south-1.aws | SHA256:oBLXcYmklqHHEbliARxEgH8IsO51rezTPiSM35BsU40 |
| Asia Pacific (Osaka) | ap-northeast-3 | ec2-serial-console.ap-northeast-3.api.aws | SHA256:Am0/jiBKBnBuFnHr9aXsgEV3G8Tu/vVHFXE/3UcyjsQ |
| Asia Pacific (Seoul) | ap-northeast-2 | serial-console.ec2-instance-connect.ap-northeast-2.aws | SHA256:FoqWXNX\$1DZ\$1\$1GuNTztg9PK49WYMqBX\$1FrcZM2dSrqrI |
| Asia Pacific (Singapore) | ap-southeast-1 | serial-console.ec2-instance-connect.ap-southeast-1.aws | SHA256:PLFNn7WnCQDHx3qmwLu1Gy/O8TUX7LQgZuaC6L45CoY |
| Asia Pacific (Sydney) | ap-southeast-2 | serial-console.ec2-instance-connect.ap-southeast-2.aws | SHA256:yFvMwUK9lEUQjQTRoXXzuN\$1cW9/VSe9W984Cf5Tgzo4 |
| Asia Pacific (Thailand) | ap-southeast-7 | ec2-serial-console.ap-southeast-7.api.aws | SHA256:KCAZiRYrR1Q2lqsg7vTwixWmvc2wmjVT31XRgSdEfDY |
| Asia Pacific (Tokyo) | ap-northeast-1 | serial-console.ec2-instance-connect.ap-northeast-1.aws | SHA256:RQfsDCZTOfQawewTRDV1t9Em/HMrFQe\$1CRlIOT5um4k |
| Canada (Central) | ca-central-1 | serial-console.ec2-instance-connect.ca-central-1.aws | SHA256:P2O2jOZwmpMwkpO6YW738FIOTHdUTyEv2gczYMMO7s4 |
| Canada West (Calgary) | ca-west-1 | ec2-serial-console.ca-west-1.api.aws | SHA256:s3rc8lI2xhbhr3iedjJNxGAFLPGOLjx7IxxXrGckk6Q |
| China (Beijing) | cn-north-1 | ec2-serial-console---cn-north-1---api.amazonwebservices.com.rproxy.govskope.us.cn | SHA256:2gHVFy4H7uU3\$1WaFUxD28v/ggMeqjvSlgngpgLgGT\$1Y |
| China (Ningxia) | cn-northwest-1 | ec2-serial-console---cn-northwest-1---api.amazonwebservices.com.rproxy.govskope.us.cn | SHA256:TdgrNZkiQOdVfYEBUhO4SzUA09VWI5rYOZGTogpwmiM |
| Europe (Frankfurt) | eu-central-1 | serial-console.ec2-instance-connect.eu-central-1.aws | SHA256:aCMFS/yIcOdOlkXvOl8AmZ1Toe\$1bBnrJJ3Fy0k0De2c |
| Europe (Ireland) | eu-west-1 | serial-console.ec2-instance-connect.eu-west-1.aws | SHA256:h2AaGAWO4Hathhtm6ezs3Bj7udgUxi2qTrHjZAwCW6E |
| Europe (London) | eu-west-2 | serial-console.ec2-instance-connect.eu-west-2.aws | SHA256:a69rd5CE/AEG4Amm53I6lkD1ZPvS/BCV3tTPW2RnJg8 |
| Europe (Milan) | eu-south-1 | ec2-serial-console.eu-south-1.api.aws | SHA256:lC0kOVJnpgFyBVrxn0A7n99ecLbXSX95cuuS7X7QK30 |
| Europe (Paris) | eu-west-3 | serial-console.ec2-instance-connect.eu-west-3.aws | SHA256:q8ldnAf9pymeNe8BnFVngY3RPAr/kxswJUzfrlxeEWs |
| Europe (Spain) | eu-south-2 | ec2-serial-console.eu-south-2.api.aws | SHA256:GoCW2DFRlu669QNxqFxEcsR6fZUz/4F4n7T45ZcwoEc |
| Europe (Stockholm) | eu-north-1 | serial-console.ec2-instance-connect.eu-north-1.aws | SHA256:tkGFFUVUDvocDiGSS3Cu8Gdl6w2uI32EPNpKFKLwX84 |
| Europe (Zurich) | eu-central-2 | ec2-serial-console.eu-central-2.api.aws | SHA256:8Ppx2mBMf6WdCw0NUlzKfwM4/IfRz4OaXFutQXWp6mk |
| Israel (Tel Aviv) | il-central-1 | ec2-serial-console.il-central-1.api.aws | SHA256:JR6q8v6kNNPi8\$1QSFQ4dj5dimNmZPTgwgsM1SNvtYyU |
| Mexico (Central) | mx-central-1 | ec2-serial-console.mx-central-1.api.aws | SHA256:BCuVl13iQNk\$1CcVnt18Ef4p2ZHUrBBAOxlFetB32GS0 |
| Middle East (Bahrain) | me-south-1 | ec2-serial-console.me-south-1.api.aws | SHA256:nPjLLKHu2QnLdUq2kVArsoK5xvPJOMRJKCBzCDqC3k8 |
| Middle East (UAE) | me-central-1 | ec2-serial-console.me-central-1.api.aws | SHA256:zpb5duKiBZ\$1l0dFwPeyykB4MPBYhI/XzXNeFSDKBvLE |
| South America (São Paulo) | sa-east-1 | serial-console.ec2-instance-connect.sa-east-1.aws | SHA256:rd2\$1/32Ognjew1yVIemENaQzC\$1Botbih62OqAPDq1dI |
| AWS GovCloud (US-East) | us-gov-east-1 | serial-console.ec2-instance-connect.us-gov-east-1.amazonaws.com | SHA256:tIwe19GWsoyLClrtvu38YEEh\$1DHIkqnDcZnmtebvF28 |
| AWS GovCloud (US-West) | us-gov-west-1 | serial-console.ec2-instance-connect.us-gov-west-1.amazonaws.com | SHA256:kfOFRWLaOZfB\$1utbd3bRf8OlPf8nGO2YZLqXZiIw5DQ |
# Disconnect from the EC2 Serial Console
If you no longer need to be connected to your instance's EC2 Serial Console, you can disconnect from it. When you disconnect from the serial console, any shell session running on the instance will continue to run. If you want to end the shell session, you'll need to end it before disconnecting from the serial console.
**Considerations**
+ The serial console connection typically lasts for 1 hour unless you disconnect from it. However, during system maintenance, Amazon EC2 will disconnect the serial console session.
+ It takes 30 seconds to tear down a session after you've disconnected from the serial console in order to allow a new session.
The way to disconnect from the serial console depends on the client.
**Browser-based client**
To disconnect from the serial console, close the serial console in-browser terminal window.
**Standard OpenSSH client**
To disconnect from the serial console, use the following command to close the SSH connection. This command must be run immediately following a new line.
```
~.
```
The command that you use for closing an SSH connection might be different depending on the SSH client that you're using.
# Troubleshoot your Amazon EC2 instance using the EC2 Serial Console
By using EC2 Serial Console, you can troubleshoot boot, network configuration, and other issues by connecting to your instance's serial port.
Use the instructions for your instance's operating system and for the tool you've configured on your instance.
**Topics**
+ [GRUB (Linux)](#grub)
+ [SysRq (Linux)](#SysRq)
+ [SAC (Windows)](#troubleshooting-sac)
**Prerequisites**
Before you begin, make sure you have completed the [ prerequisites](ec2-serial-console-prerequisites.md), including configuring your chosen troubleshooting tool.
## (Linux instances) Use GRUB to troubleshoot your instance
GNU GRUB (short for GNU GRand Unified Bootloader, commonly referred to as GRUB) is the default boot loader for most Linux operating systems. From the GRUB menu, you can select which kernel to boot into, or modify menu entries to change how the kernel will boot. This can be useful when troubleshooting a failing instance.
The GRUB menu is displayed during the boot process. The menu is not accessible via normal SSH, but you can access it using the EC2 Serial Console.
You can boot into single user mode or emergency mode. Single user mode will boot the kernel at a lower runlevel. For example, it might mount the filesystem but not activate the network, giving you the opportunity to perform the maintenance necessary to fix the instance. Emergency mode is similar to single user mode except that the kernel runs at the lowest runlevel possible.
**To boot into single user mode**
1. [Connect](connect-to-serial-console.md) to the instance's serial console.
1. Reboot the instance using the following command.
```
[ec2-user ~]$ sudo reboot
```
1. During reboot, when the GRUB menu appears, press any key to stop the boot process.
1. In the GRUB menu, use the arrow keys to select the kernel to boot into, and press `e` on your keyboard.
1. Use the arrow keys to locate your cursor on the line containing the kernel. The line begins with either `linux` or `linux16` depending on the AMI that was used to launch the instance. For Ubuntu, two lines begin with `linux`, which must both be modified in the next step.
1. At the end of the line, add the word `single`.
The following is an example for Amazon Linux 2.
```
linux /boot/vmlinuz-4.14.193-149.317.amzn2.aarch64 root=UUID=d33f9c9a-\
dadd-4499-938d-ebbf42c3e499 ro console=tty0 console=ttyS0,115200n8 net.ifname\
s=0 biosdevname=0 nvme_core.io_timeout=4294967295 rd.emergency=poweroff rd.she\
ll=0 single
```
1. Press **Ctrl\$1X** to boot into single user mode.
1. At the `login` prompt, enter the username of the password-based user that you [set up previously](configure-access-to-serial-console.md#set-user-password), and then press **Enter**.
1. At the `Password` prompt, enter the password, and then press **Enter**.
**To boot into emergency mode**
Follow the same steps as single user mode, but at step 6, add the word `emergency` instead of `single`.
## (Linux instances) Use SysRq to troubleshoot your instance
The System Request (SysRq) key, which is sometimes referred to as "magic SysRq", can be used to directly send the kernel a command, outside of a shell, and the kernel will respond, regardless of what the kernel is doing. For example, if the instance has stopped responding, you can use the SysRq key to tell the kernel to crash or reboot. For more information, see [Magic SysRq key](https://en.wikipedia.org/wiki/Magic_SysRq_key) in Wikipedia.
You can use SysRq commands in the EC2 Serial Console browser-based client or in an SSH client. The command to send a break request is different for each client.
To use SysRq, choose one of the following procedures based on the client that you are using.
------
#### [ Browser-based client ]
**To use SysRq in the serial console browser-based client**
1. [Connect](connect-to-serial-console.md) to the instance's serial console.
1. To send a break request, press `CTRL+0` (zero). If your keyboard supports it, you can also send a break request using the Pause or Break key.
```
[ec2-user ~]$ CTRL+0
```
1. To issue a SysRq command, press the key on your keyboard that corresponds to the required command. For example, to display a list of SysRq commands, press `h`.
```
[ec2-user ~]$ h
```
The `h` command outputs something similar to the following.
```
[ 1169.389495] sysrq: HELP : loglevel(0-9) reboot(b) crash(c) terminate-all-tasks(e) memory-full-oom-kill(f) kill-all-tasks(i) thaw-filesystems
(j) sak(k) show-backtrace-all-active-cpus(l) show-memory-usage(m) nice-all-RT-tasks(n) poweroff(o) show-registers(p) show-all-timers(q) unraw(r
) sync(s) show-task-states(t) unmount(u) show-blocked-tasks(w) dump-ftrace-buffer(z)
```
------
#### [ SSH client ]
**To use SysRq in an SSH client**
1. [Connect](connect-to-serial-console.md) to the instance's serial console.
1. To send a break request, press `~B` (tilde, followed by uppercase `B`).
```
[ec2-user ~]$ ~B
```
1. To issue a SysRq command, press the key on your keyboard that corresponds to the required command. For example, to display a list of SysRq commands, press `h`.
```
[ec2-user ~]$ h
```
The `h` command outputs something similar to the following.
```
[ 1169.389495] sysrq: HELP : loglevel(0-9) reboot(b) crash(c) terminate-all-tasks(e) memory-full-oom-kill(f) kill-all-tasks(i) thaw-filesystems
(j) sak(k) show-backtrace-all-active-cpus(l) show-memory-usage(m) nice-all-RT-tasks(n) poweroff(o) show-registers(p) show-all-timers(q) unraw(r
) sync(s) show-task-states(t) unmount(u) show-blocked-tasks(w) dump-ftrace-buffer(z)
```
**Note**
The command that you use for sending a break request might be different depending on the SSH client that you're using.
------
## (Windows instances) Use SAC to troubleshoot your instance
The Special Admin Console (SAC) capability of Windows provides a way to troubleshoot a Windows instance. By connecting to the instance's serial console and using SAC, you can interrupt the boot process and boot Windows in safe mode.
**Note**
If you enable SAC on an instance, the EC2 services that rely on password retrieval will not work from the Amazon EC2 console. Windows on Amazon EC2 launch agents (EC2Config, EC2Launch v1, and EC2Launch v2) rely on the serial console to execute various tasks. These tasks do not perform successfully when you enable SAC on an instance. For more information about Windows on Amazon EC2 launch agents, see [Configure your Amazon EC2 Windows instance](ec2-windows-instances.md). If you enable SAC, you can disable it later. For more information, see [Disable SAC and the boot menu](#disable-sac-bootmenu).
**Topics**
+ [Use SAC](#use-sac)
+ [Use the boot menu](#use-boot-menu)
+ [Disable SAC and the boot menu](#disable-sac-bootmenu)
### Use SAC
**To use SAC**
1. [Connect to the serial console.](connect-to-serial-console.md)
If SAC is enabled on the instance, the serial console displays the `SAC>` prompt.
![\[SAC prompt displayed in the serial console.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-3.png)
1. To display the SAC commands, enter ?, and then press **Enter**.
Expected output
![\[Enter a question mark to display the SAC commands.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-4.png)
1. To create a command prompt channel (such as `cmd0001` or `cmd0002`), enter cmd, and then press **Enter**.
1. To view the command prompt channel, press **ESC**, and then press **TAB**.
Expected output
![\[The command prompt channel.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-5.png)
1. To switch channels, press **ESC\$1TAB\$1channel number** together. For example, to switch to the `cmd0002` channel (if it has been created), press **ESC\$1TAB\$12**.
1. Enter the credentials required by the command prompt channel.
![\[The command prompt requiring credentials.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-6.png)
The command prompt is the same full-featured command shell that you get on a desktop, but with the exception that it does not allow the reading of characters that were already output.
![\[A full-featured command shell.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-7.png)
**PowerShell can also be used from the command prompt.**
Note that you might need to set the progress preference to silent mode.
![\[PowerShell within the command prompt.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-8.png)
### Use the boot menu
If the instance has the boot menu enabled and is restarted after connecting through SSH, you should see the boot menu, as follows.
![\[Boot menu in the command prompt.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-1.png)
**Boot menu commands**
ENTER
Starts the selected entry of the operating system.
TAB
Switches to the Tools menu.
ESC
Cancels and restarts the instance.
ESC followed by 8
Equivalent to pressing **F8**. Shows advanced options for the selected item.
ESC key \$1 left arrow
Goes back to the initial boot menu.
The ESC key alone does not take you back to the main menu because Windows is waiting to see if an escape sequence is in progress.
![\[Advanced boot options.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/win-boot-2.png)
### Disable SAC and the boot menu
If you enable SAC and the boot menu, you can disable these features later.
Use one of the following methods to disable SAC and the boot menu on an instance.
------
#### [ PowerShell ]
**To disable SAC and the boot menu on a Windows instance**
1. [Connect](connecting_to_windows_instance.md) to your instance and perform the following steps from an elevated PowerShell command line.
1. First disable the boot menu by changing the value to `no`.
```
bcdedit /set '{bootmgr}' displaybootmenu no
```
1. Then disable SAC by changing the value to `off`.
```
bcdedit /ems '{current}' off
```
1. Apply the updated configuration by rebooting the instance.
```
shutdown -r -t 0
```
------
#### [ Command prompt ]
**To disable SAC and the boot menu on a Windows instance**
1. [Connect](connecting_to_windows_instance.md) to your instance and perform the following steps from the command prompt.
1. First disable the boot menu by changing the value to `no`.
```
bcdedit /set {bootmgr} displaybootmenu no
```
1. Then disable SAC by changing the value to `off`.
```
bcdedit /ems {current} off
```
1. Apply the updated configuration by rebooting the instance.
```
shutdown -r -t 0
```
------
# Send a diagnostic interrupt to debug an unreachable Amazon EC2 instance
**Warning**
Diagnostic interrupts are intended for use by advanced users. Incorrect usage could negatively impact your instance. Sending a diagnostic interrupt to an instance could trigger an instance to crash and reboot, which could lead to the loss of data.
You can send a diagnostic interrupt to an unreachable or unresponsive instance to manually trigger a *kernel panic* for a Linux instance, or a *stop error* (commonly referred to as a *blue screen error*) for a Windows instance.
**Linux instances**
Linux operating systems typically crash and reboot when a kernel panic occurs. The specific behavior of the operating system depends on its configuration. A kernel panic can also be used to cause the instance's operating system kernel to perform tasks, such as generating a crash dump file. You can then use the information in the crash dump file to conduct root cause analysis and debug the instance. The crash dump data is generated locally by the operating system on the instance itself.
**Windows instances**
In general, Windows operating systems crash and reboot when a stop error occurs, but the specific behavior depends on its configuration. A stop error can also cause the operating system to write debugging information, such as a kernel memory dump, to a file. You can then use this information to conduct root cause analysis to debug the instance. The memory dump data is generated locally by the operating system on the instance itself.
Before sending a diagnostic interrupt to your instance, we recommend that you consult the documentation for your operating system and then make the necessary configuration changes.
**Topics**
+ [Supported instance types](#diagnostic-interrupt-instances)
+ [Prerequisites](#diagnostic-interrupt-prereqs)
+ [Send a diagnostic interrupt](#diagnostic-interrupt-use)
## Supported instance types
Diagnostic interrupt is supported on all Nitro-based instance types, except those powered by AWS Graviton processors. For more information, see [instances built on the AWS Nitro System](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-nitro-instances.html) and [AWS Graviton](https://aws.amazon.com/ec2/graviton/).
## Prerequisites
Before using a diagnostic interrupt, you must configure your instance's operating system. This ensures that it performs the actions that you need when a kernel panic (Linux instances) or stop error (Windows instances) occurs.
### Linux instances
**To configure Amazon Linux 2 or Amazon Linux 2023 to generate a crash dump when a kernel panic occurs**
1. Connect to your instance.
1. Install **kexec** and **kdump**.
```
[ec2-user ~]$ sudo yum install kexec-tools -y
```
1. Configure the kernel to reserve an appropriate amount of memory for the secondary kernel. The amount of memory to reserve depends on the total available memory of your instance. Open the `/etc/default/grub` file using your preferred text editor, locate the line that starts with `GRUB_CMDLINE_LINUX_DEFAULT`, and then add the `crashkernel` parameter in the following format: `crashkernel=memory_to_reserve`. For example, to reserve `256MB`, modify the `grub` file as follows:
```
GRUB_CMDLINE_LINUX_DEFAULT="crashkernel=256M console=tty0 console=ttyS0,115200n8 net.ifnames=0 biosdevname=0 nvme_core.io_timeout=4294967295 rd.emergency=poweroff rd.shell=0"
GRUB_TIMEOUT=0
GRUB_DISABLE_RECOVERY="true"
```
1. Save the changes and close the `grub` file.
1. Rebuild the GRUB2 configuration file.
```
[ec2-user ~]$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
```
1. On instances based on Intel and AMD processors, the `send-diagnostic-interrupt` command sends an *unknown non-maskable interrupt* (NMI) to the instance. You must configure the kernel to crash when it receives the unknown NMI. Open the `/etc/sysctl.conf` file using your preferred text editor and add the following.
```
kernel.unknown_nmi_panic=1
```
1. Reboot and reconnect to your instance.
1. Verify that the kernel has been booted with the correct `crashkernel` parameter.
```
$ grep crashkernel /proc/cmdline
```
The following example output indicates successful configuration.
```
BOOT_IMAGE=/boot/vmlinuz-4.14.128-112.105.amzn2.x86_64 root=UUID=a1e1011e-e38f-408e-878b-fed395b47ad6 ro crashkernel=256M console=tty0 console=ttyS0,115200n8 net.ifnames=0 biosdevname=0 nvme_core.io_timeout=4294967295 rd.emergency=poweroff rd.shell=0
```
1. Verify that the **kdump** service is running.
```
[ec2-user ~]$ systemctl status kdump.service
```
The following example output shows the result if the **kdump** service is running.
```
kdump.service - Crash recovery kernel arming
Loaded: loaded (/usr/lib/systemd/system/kdump.service; enabled; vendor preset: enabled)
Active: active (exited) since Fri 2019-05-24 23:29:13 UTC; 22s ago
Process: 2503 ExecStart=/usr/bin/kdumpctl start (code=exited, status=0/SUCCESS)
Main PID: 2503 (code=exited, status=0/SUCCESS)
```
**Note**
By default, the crash dump file is saved to `/var/crash/`. To change the location, modify the `/etc/kdump.conf` file using your preferred text editor.
**To configure SUSE Linux Enterprise, Ubuntu, or Red Hat Enterprise Linux**
On instances based on Intel and AMD processors, the `send-diagnostic-interrupt` command sends an *unknown non-maskable interrupt* (NMI) to the instance. You must configure the kernel to crash when it receives the unknown NMI by adjusting the configuration file for your operating system. For information about how to configure the kernel to crash, see the documentation for your operating system:
+ [SUSE Linux Enterprise](https://www.suse.com/support/kb/doc/?id=3374462)
+ [Ubuntu](https://ubuntu.com/server/docs/kernel-crash-dump)
+ [ Red Hat Enterprise Linux (RHEL)](https://access.redhat.com/solutions/6038)
### Windows instances
**To configure Windows to generate a memory dump when a stop error occurs**
1. Connect to your instance.
1. Open the **Control Panel** and choose **System**, **Advanced system settings**.
1. In the **System Properties** dialog box, choose the **Advanced** tab.
1. In the **Startup and Recovery** section, choose **Settings...**.
1. In the **System failure** section, configure the settings as needed, and then choose **OK**.
For more information about configuring Windows stop errors, see [ Overview of memory dump file options for Windows](https://support.microsoft.com/en-us/help/254649/overview-of-memory-dump-file-options-for-windows).
## Send a diagnostic interrupt
After you have completed the necessary configuration changes, you can send a diagnostic interrupt to your instance using the AWS CLI or Amazon EC2 API.
------
#### [ AWS CLI ]
**To send a diagnostic interrupt to your instance**
Use the [send-diagnostic-interrupt](https://docs.aws.amazon.com/cli/latest/reference/ec2/send-diagnostic-interrupt.html) command.
```
aws ec2 send-diagnostic-interrupt --instance-id i-1234567890abcdef0
```
------
#### [ PowerShell ]
**To send a diagnostic interrupt to your instance**
Use the [Send-EC2DiagnosticInterrupt](https://docs.aws.amazon.com/powershell/latest/reference/items/Send-EC2DiagnosticInterrupt.html) cmdlet.
```
Send-EC2DiagnosticInterrupt -InstanceId i-1234567890abcdef0
```
------