az-serial-console

Connect to a serial console

$ az serial-console connect --resource-group [Resource_Group_Name] --name [Virtual_Machine_Name]

$ <Ctrl ]>

az serial-console connect --resource-group {resource_group} --name {vm_name} [--instance-id {instance_id}]

--resource-group
    Name of resource group. You can configure the default group using `az configure --defaults group=`.

--name
    The name of the virtual machine or virtual machine scale set.

--instance-id
    The instance ID of the virtual machine scale set instance. If not specified, the command connects to the default instance (instance 0).

The `az serial-console connect` command establishes a connection to the serial console of an Azure Virtual Machine (VM) or Virtual Machine Scale Set (VMSS) instance. This provides a text-based interface for interacting with the VM, even when network connectivity is unavailable. This is particularly useful for troubleshooting boot issues, diagnosing network configuration problems, and performing other low-level system administration tasks.

The serial console operates independently of the operating system's network configuration, relying instead on the Serial over LAN (SOL) functionality available on most modern VMs. It allows you to directly interact with the VM's bootloader, kernel, and other system components, enabling you to diagnose and potentially resolve issues that prevent the VM from booting or operating normally. Access requires appropriate Azure role-based access control (RBAC) permissions. The VM must have Boot Diagnostics enabled, or the serial console must be explicitly enabled.

Use is commonly employed in scenarios like troubleshooting inaccessible VMs, emergency access, and system recovery.

Important: This command depends on the Azure CLI and the Serial Console feature in Azure. Ensure both are properly configured for optimal functionality.

Serial console access requires appropriate Azure RBAC permissions. The VM or VMSS instance must have Boot Diagnostics enabled, or the serial console must be explicitly enabled within the boot settings (on the operating system level).

If the OS firewall is active, ensure it doesn't block access to the serial port. In some scenarios (e.g., a crashed VM), the serial console might not be responsive. Make sure boot diagnostics are enabled for screenshots and boot error output.

Before using `az serial-console connect`, ensure that the Azure CLI is installed and configured, and that you are logged in to your Azure subscription. Also, confirm that the target VM or VMSS instance has Boot Diagnostics enabled.

Boot Diagnostics are enabled by default for VMs created via the Azure portal/CLI, but may need to be explicitly enabled if created via other methods (e.g., ARM templates, custom images, etc.). The feature will automatically direct serial console logs to an Azure Storage account.

If the connection fails, verify that the VM is running. Check the Boot Diagnostics logs for potential boot failures that might prevent the serial console from becoming available. Confirm that your Azure account has the necessary permissions to access the VM and the serial console functionality. Also, double-check the resource group and VM/VMSS instance name for any typos.

az vm boot-diagnostics get-boot-log(1)