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.
- You must be using the resource management deployment model. Classic deployments are not supported.
- Virtual machine MUST have boot diagnostics enabled
- The account using the serial console must have Contributor role for VM and the boot diagnostics storage account.
- For settings specific to Linux distro, see Accessing the serial console for Linux
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
- Open the Azure portal
- In the left menu, select virtual machines.
- Click on the VM in the list. The overview page for the VM will open.
- 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.
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.
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"
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 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.
All data that is sent back and forth is encrypted on the wire.
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.
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.
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.
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.
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||
|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:
Most errors are transient in nature and retrying the serial console connection often addresses these. Below table shows a list of errors and mitigation
|Unable to retrieve boot diagnostics settings for '
||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 '
||Serial console access requires certain permission to access. See access requirements for details|
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
|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 email@example.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.