Home / Azure

AzureHow-toBeginner

Introduction to Azure VM boot diagnostics and Serial Console: see why a VM won't boot

Enable boot diagnostics, read the boot screenshot and serial log, and use Serial Console to log in to a Windows or Linux VM that has no network, with az CLI commands for each step.

Deepak Bhardwaj5 min read

Applies toAzure Virtual Machines (Windows Server, Linux), managed boot diagnostics storage, Azure CLI 2.x

Why you need these two tools

When a VM is "Running" in the portal but RDP or SSH times out, you have no idea what the guest OS is doing. Two built-in features show you:

Feature What it gives you Needs network to the VM?
Boot diagnostics A screenshot of the VM console and the serial log (Linux and Windows boot output) No
Serial Console An interactive text console (Linux shell or Windows SAC/CMD) No

Serial Console depends on boot diagnostics, so turn that on first.

Step 1: Enable boot diagnostics

Use managed storage (no storage account to look after):

az vm boot-diagnostics enable --resource-group rg-app --name vm-app01

To use your own storage account instead (for example, when policy requires it):

az vm boot-diagnostics enable --resource-group rg-app --name vm-app01 \
  --storage https://stbootdiag01.blob.core.windows.net/

Tip

Turn boot diagnostics on in your VM templates and with Azure Policy. You can enable it on a VM that is already broken, but the serial log only captures output from that point on, so having it on from day one gives you the boot history you need.

Step 2: Read the screenshot and serial log

# Download the latest screenshot and serial log URIs
az vm boot-diagnostics get-boot-log-uris --resource-group rg-app --name vm-app01

# Print the serial log text directly
az vm boot-diagnostics get-boot-log --resource-group rg-app --name vm-app01 | tail -50

In the portal: VM > Help > Boot diagnostics, with tabs for Screenshot and Serial log.

What the screenshot usually tells you (Windows)

Screenshot shows Likely cause Next step
Login screen (Ctrl+Alt+Del) OS is up; problem is network, firewall or RDP service Check NSG, Windows Firewall, RDP service via Serial Console
"Applying updates" / "Working on updates" Windows Update in progress Wait; don't restart repeatedly
Blue screen with stop code Driver, disk or registry problem Note the stop code; repair VM process
"Preparing Automatic Repair" loop Boot configuration or disk corruption Attach OS disk to a repair VM

What the serial log usually tells you (Linux)

Log shows Likely cause
You are in emergency mode Bad /etc/fstab entry (often a data disk that's gone)
Kernel panic - not syncing: VFS: Unable to mount root fs Broken kernel/initramfs after update
cloud-init errors then a login prompt OS is up; network/SSH problem
Repeated XFS or EXT4-fs error File system corruption

Step 3: Connect with Serial Console

Portal: VM > Help > Serial console. Or from the CLI (needs the serial-console extension):

az extension add --name serial-console
az serial-console connect --resource-group rg-app --name vm-app01

Requirements:

  • Boot diagnostics enabled.
  • Your account has Virtual Machine Contributor (or higher) on the VM.
  • Linux: a local user with a password (SSH-key-only users can't log in at the console). Set one with az vm user update --username azureuser --password '<strong password>' before you need it.
  • Windows: SAC (Special Administration Console) is enabled by default on Azure Marketplace images.

Windows: from SAC to a command prompt

SAC> cmd
SAC> ch -si 1

Log in with a local admin account, then check the usual suspects:

:: Is RDP listening?
netstat -ano | findstr :3389

:: Is the RDP service running?
sc query TermService

:: Is RDP allowed?
reg query "HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server" /v fDenyTSConnections

:: Temporarily allow RDP through Windows Firewall
netsh advfirewall firewall set rule group="remote desktop" new enable=yes

Start PowerShell inside it with powershell if you prefer.

Linux: fix a bad fstab from the console

# In emergency mode, remount root read-write
mount -o remount,rw /

# Comment out the failing entry
vi /etc/fstab

# Add nofail to data disks so this never blocks boot again
# UUID=xxxx  /data  xfs  defaults,nofail  0  2
systemctl daemon-reload
reboot

When Serial Console isn't enough

If the OS doesn't reach a console at all (blue screen loop, kernel panic), use the repair VM extension. It snapshots the OS disk, attaches a copy to a new rescue VM and lets you fix it offline:

az extension add --name vm-repair
az vm repair create --resource-group rg-app --name vm-app01 \
  --repair-username repairadmin --repair-password '<strong password>' --verbose
# fix the disk on the repair VM, then:
az vm repair restore --resource-group rg-app --name vm-app01 --verbose

Warning

vm repair restore swaps the repaired copy in as the VM's OS disk and deletes the repair VM. Check the original disk is still there (it is kept by default) before you clean anything up, and take your own snapshot first if the VM holds data you can't rebuild.

Prevent it next time

  • Enable boot diagnostics on every VM through policy, and give operators Virtual Machine Contributor through PIM so they can open Serial Console during incidents.
  • On Linux, keep a break-glass local user with a password stored in Key Vault.
  • Use nofail on all non-root mounts in /etc/fstab.
  • Keep a runbook link to this page in your VM alerting so on-call knows the console exists before they need it.

Related fixes