Virtual Machine Serial Console (preview)

The Virtual Machine Serial Console on Azure provides access to a text-based console for Linux and Windows virtual machines. This serial connection is to COM1 serial port of the virtual machine and provides access to the virtual machine and are not related to virtual machine's network / operating system state. Access to the serial console for a virtual machine can be done only via Azure portal currently and allowed only for those users who have VM Contributor or above access to the virtual machine.

Note

Previews are made available to you on the condition that you agree to the terms of use. For more information, see Microsoft Azure Supplemental Terms of Use for Microsoft Azure Previews. Currently this service is in public preview and access to the serial console for virtual machines is available to global Azure regions. At this point serial console is not available Azure Government, Azure Germany, and Azure China cloud.

Prerequisites

Open the Serial Console

Serial console for virtual machines is only accessible via Azure portal. Below are the steps to access serial console for virtual machines via portal

  1. Open the Azure portal
  2. In the left menu, select virtual machines.
  3. Click on the VM in the list. The overview page for the VM will open.
  4. Scroll down to the Support + Troubleshooting section and click on serial console (Preview) option. A new pane with the serial console will open and start the connection.

Note

Serial console requires a local user with a password configured. At this time, VMs only configured with SSH public key will not have access to the serial console. To create a local user with password, follow VM Access Extension and create local user with password.

Disable Serial Console

By default, all subscriptions have serial console access enabled for all VMs. You may disable serial console at either the subscription level or VM level.

Subscription-level disable

Serial console can be disabled for an entire subscription by through the Disable Console REST API call. You may use the "Try It" functionality available on the API Documentation page to disable and enable Serial Console for a subscription. Enter your subscriptionId, "default" in the default field, and click Run. Azure CLI commands are not yet available and will arrive at a later date. Try the REST API call here.

Alternatively, you may use the set of commands below in Cloud Shell (bash commands shown) to disable, enable, and view the disbled status of serial console for a subscription.

  • To get the disabled status of serial console for a subscription:

    $ export ACCESSTOKEN=($(az account get-access-token --output=json | jq .accessToken | tr -d '"')) 
    
    $ export SUBSCRIPTION_ID=$(az account show --output=json | jq .id -r)
    
    $ curl "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.SerialConsole/consoleServices/default?api-version=2018-05-01" -H "Authorization: Bearer $ACCESSTOKEN" -H "Content-Type: application/json" -H "Accept: application/json" -s | jq .properties
    
  • To disable serial console for a subscription:

    $ export ACCESSTOKEN=($(az account get-access-token --output=json | jq .accessToken | tr -d '"')) 
    
    $ export SUBSCRIPTION_ID=$(az account show --output=json | jq .id -r)
    
    $ curl -X POST "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.SerialConsole/consoleServices/default/disableConsole?api-version=2018-05-01" -H "Authorization: Bearer $ACCESSTOKEN" -H "Content-Type: application/json" -H "Accept: application/json" -s -H "Content-Length: 0"
    
  • To enable serial console for a subscription:

    $ export ACCESSTOKEN=($(az account get-access-token --output=json | jq .accessToken | tr -d '"')) 
    
    $ export SUBSCRIPTION_ID=$(az account show --output=json | jq .id -r)
    
    $ curl -X POST "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.SerialConsole/consoleServices/default/enableConsole?api-version=2018-05-01" -H "Authorization: Bearer $ACCESSTOKEN" -H "Content-Type: application/json" -H "Accept: application/json" -s -H "Content-Length: 0"
    

VM-level disable

Serial console can be disabled for specific VMs by disabling that VM's boot diagnostics setting. Simply turn off boot diagnostics from the Azure portal and serial console will be disabled for the VM.

Serial Console security

Access security

Access to Serial console is limited to users who have VM Contributors or above access to the virtual machine. If your AAD tenant requires Multi-Factor Authentication then access to the serial console will also need MFA as its access is via Azure portal.

Channel security

All data that is sent back and forth is encrypted on the wire.

Audit logs

All access to the serial console is currently logged in the boot diagnostics logs of the virtual machine. Access to these logs are owned and controlled by the Azure virtual machine administrator.

Caution

While no access passwords for the console are logged, if commands run within the console contain or output passwords, secrets, user names or any other form of Personally Identifiable Information (PII), those will be written to the virtual machine boot diagnostics logs, along with all other visible text, as part of the implementation of the serial console's scrollback functionality. These logs are circular and only individuals with read permissions to the diagnostics storage account have access to them, however we recommend following the best practice of using the SSH console for anything that may involve secrets and/or PII.

Concurrent usage

If a user is connected to serial console and another user successfully requests access to that same virtual machine, the first user will be disconnected and the second user connected in a manner akin to the first user standing up and leaving the physical console and a new user sitting down.

Caution

This means that the user who gets disconnected will not be logged out! The ability to enforce a logout upon disconnect (via SIGHUP or similar mechanism) is still in the roadmap. For Windows there is an automatic timeout enabled in SAC, however for Linux you can configure terminal timeout setting. To do this simply add export TMOUT=600 in your .bash_profile or .profile for the user you logon in the console with, to timeout the session after 10 minutes.

Disable feature

The serial console functionality can be deactivated for specific VMs by disabling that VM's boot diagnostics setting.

Common scenarios for accessing serial console

Scenario Actions in serial console OS Applicability
Broken FSTAB file Enter key to continue and fix fstab file using a text editor. You may need to be in single user mode for this. See how to fix fstab issues and Using Serial Console to access GRUB and Single User Mode to get started. Linux
Incorrect firewall rules Access serial console and fix iptables or Windows firewall rules. Linux/Windows
Filesystem corruption/check Access serial console and recover filesystem. Linux/Windows
SSH/RDP configuration issues Access serial console and change settings. Linux/Windows
Network lock down system Access serial console via portal to manage system. Linux/Windows
Interacting with bootloader Access GRUB/BCD via the serial console. Go to Using Serial Console to access GRUB and Single User Mode to get started. Linux/Windows

Access Serial Console for Linux

In order for serial console to function properly, the guest operating system must be configured to read and write console messages to the serial port. Most Endorsed Azure Linux Distributions have the serial console configured by default. Simply clicking the Serial Console section in the Azure portal will provide access to the console.

Distro Serial Console access
Red Hat Enterprise Linux Red Hat Enterprise Linux Images available on Azure have console access enabled by default.
CentOS CentOS images available on Azure have console access enabled by default.
Ubuntu Ubuntu images available on Azure have console access enabled by default.
CoreOS CoreOS images available on Azure have console access enabled by default.
SUSE Newer SLES images available on Azure have console access enabled by default. If you are using older versions (10 or below) of SLES on Azure, follow the KB article to enable serial console.
Oracle Linux Oracle Linux images available on Azure have console access enabled by default.
Custom Linux images To enable serial console for your custom Linux VM image, enable console access in /etc/inittab to run a terminal on ttyS0. Here is an example to add this in the inittab file: S0:12345:respawn:/sbin/agetty -L 115200 console vt102. For more information on properly creating custom images see Create and upload a Linux VHD in Azure.

Errors

Most errors are transient in nature and retrying the serial console connection often addresses these. Below table shows a list of errors and mitigation

Error Mitigation
Unable to retrieve boot diagnostics settings for ''. To use the serial console, ensure that boot diagnostics is enabled for this VM. Ensure that the VM has boot diagnostics enabled.
The VM is in a stopped deallocated state. Start the VM and retry the serial console connection. Virtual machine must be in a started state to access the serial console
You do not have the required permissions to use this VM the serial console. Ensure you have at least VM Contributor role permissions. Serial console access requires certain permission to access. See access requirements for details
Unable to determine the resource group for the boot diagnostics storage account ''. Verify that boot diagnostics is enabled for this VM and you have access to this storage account. Serial console access requires certain permission to access. See access requirements for details

Known issues

As we are still in the preview stages for serial console access, we are working through some known issues, below is the list of these with possible workarounds

Issue Mitigation
There is no option with virtual machine scale set instance serial console At the time of preview, access to the serial console for virtual machine scale set instances is not supported.
Hitting enter after the connection banner does not show a log in prompt Hitting enter does nothing

Frequently asked questions

Q. How can I send feedback?

A. Provide feedback as an issue by going to https://aka.ms/serialconsolefeedback. Alternatively (less preferred) Send feedback via azserialhelp@microsoft.com or in the virtual machine category of http://feedback.azure.com

Q. I am not able to access the serial console, where can I file a support case?

A. This preview feature is covered via Azure Preview Terms. Support for this is best handled via channels mentioned above.

Next steps