Collecting core dumps
Use core dumps to analyze the causes of an unresponsive virtual machine (VM)instance.
To collect core dumps on Compute Engine, you must configure yourVMs to receive aNon-Maskable Interrupt (NMI) signal, and then run aSendDiagnosticInterrupt command to prompt a kernel panic or blue screen inyour operating system. A kernel panic or blue screen starts a core dumpcollection by the guest operating system. These core dumps can then be used fordebugging purposes especially in scenarios that are hard to reproduce, such asa kernel freeze.
Before you begin
- Sending NMI signals are counted in the defaultQueries API quota. Formore information, seeAPI rate limits.
- If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
gcloud
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
Required roles
To ensure that your user or service account has the necessary permission to send NMI signals to a VM, ask your administrator to grant your user or service account theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.
This predefined role contains the compute.instances.sendDiagnosticInterrupt permission, which is required to send NMI signals to a VM.
Your administrator might also be able to give your user or service account this permission withcustom roles or otherpredefined roles.
Overview
To use core dumps to help debug an unresponsive VM or a security issue,you need to complete the following steps:
- Configure your VM to generate core dumps
- Send an NMI signal to generate core dumps
- Review the core dumps
Limitations
For VMs that have Secure Boot enabled, you must disable Secure boot before you sendan NMI interrupt signal. For instructions, seeModifying Shielded VM options on a VM instance.
Configure VM
A VM's response to receiving an NMI interrupt signal depends on the VM'soperating system configuration.
Each operating system writes its core dump logs in a different location. Forexample in Ubuntu operating systems the crash dump file is saved to/var/crash/ by default.
To configure your guest OS to generate a crash dump when an NMI signal isreceived, review the documentation for the supported operating system.
| Operating system | Links to instructions | Additional notes |
|---|---|---|
| Ubuntu | Ubuntu: Kernelcrash dump | For Linux VMs, you must configure the kernel to crash when it receives theNMI interrupt signal. To configure the kernel to crash, add the following to your configurationfile: kernel.unknown_nmi_panic=1 |
| SUSE Linux Enterprise Server (SLES) | Configurecrashkernel memory for kernel core dump analysis | |
| Red Hat Enterprise Linux (RHEL) | Use both of the following documents: | |
| Container-Optimized OS (COS) | EnablingKernel Crash Dump on GCE COS Instances | Only COS 93 and later support kdump generation using NMI signal. |
| Windows | Generatea kernel or complete crash dump | Windows client VMs don't keep memory dump files unless they are members of anAD domain or the following is true:
For more information, seeKernel dump storage and clean up behavior in Windows 7 |
Send NMI to generate core dumps
After you configure the VM, you can then send the NMI signal to the VM by usingeither theGoogle Cloud CLI, orREST.
Note: When you configure your VM to trigger kernel panicand generate crash dumps, the VM becomes unreachable after the NMI signalis sent. If you want to connect to the VM after the signal is sent, you needto restart the VM.gcloud
To send the NMI signal, use theinstances send-diagnostic-interrupt command.
gcloud compute instances send-diagnostic-interruptVM_NAME \ --zone=ZONE
Replace the following:
VM_NAME: instance ID or name of the VM thatyou want to collect core dumps fromZONE: the zone where your VM is located
The output is similar to the following:
<Empty Response>
For a complete list of outputs, see the next section in this document about"NMI command responses".
REST
Optional. If not already available, create an API key.For more information about creating API keys, seeCreating an API key.
To send the NMI signal, make a
POSTrequest to thesendDiagnosticInterruptmethod.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/sendDiagnosticInterrupt?key=API_KEY
For, example, you can use the
curlcommand to make the request as follows:curl --request POST 'https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/sendDiagnosticInterrupt?key=API_KEY' \ --header 'Authorization: Bearer $(gcloud auth print-access-token)' \ --header 'Accept: application/json' \ --compressed
Replace the following:
PROJECT_ID: ID of the project to create the VM inZONE: the zone where your VM is locatedVM_NAME: instance ID or name of the VM thatyou want to collect core dumps fromAPI_KEY: your API key
The output is similar to the following:
<Empty Response>
For a complete list of outputs, see the next section in this documentabout "NMI command responses".
NMI command responses
One of the following responses are returned when you attempt to send anNMI signal.
| State | Body | Notes |
|---|---|---|
| SUCCESS | <Empty Response> | SUCCESS shows that the NMI signal is delivered to theoperating system. It does not guarantee that the core dump is collected, orthat the VM shuts down or reboots. These behaviors are determined by theoperating system configuration. |
| FAIL | UNSUPPORTED_OPERATION | This occurs when the operating system fails to receive the NMI signal. Thereare multiple reasons for this. Common scenarios are that the VM is beinglive migrated or the VMis not properly configured to receive NMI signals. To resolve this, you can try the following:
|
| FAIL | Required 'compute.instances.sendDiagnosticInterrupt' permission for [..] | The command failed because the user making the request does not havesufficient permissions. To resolve this, you can assign a role to the user that contains the compute.instances.sendDiagnosticInterrupt permission. |
Review core dumps
Review the crash dump file in the configured or default location for youroperating system.
For example in Ubuntu operating systems, by default, the crash dump file issaved to/var/crash/.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-09 UTC.