Access the serial console of a VM application

You can open a serial console session to a running Linux VM application to debug boot failures, kernel panics, and network issues when SSH is unavailable.

Before you begin

  • The VM application is in the Running state.
  • The Linux guest kernel has console=ttyS0 configured in its kernel command line.
  • You have get permission on the devices/applications/console resource in Red Hat Edge Manager.

Procedure

  1. To open a serial console session from the Red Hat Edge Manager web console:
    1. Navigate to the device details page and locate the VM application.
    2. Click Open console.

      Only users with get permission on the devices/applications/console resource can see the button. The button is disabled when the VM is not in the Running state.

      Alternatively, navigate to the Terminal tab, select the VM console subtab, and select the VM application from the dropdown.

    3. An in-browser terminal opens that is connected to the VM serial port. Log in with the default user account defined by the guest image. Common examples include cloud-user for Red Hat Enterprise Linux cloud images and fedora for community Fedora container disk images. If you use a different guest image, check that image’s documentation for its default user. If you set a password in the guided form, use that password with the default user account. Type commands to interact with the guest operating system.

      The session closes when you navigate to a different section in the web console or close the browser tab.

  2. To open a serial console session from the CLI, run the following command: 
    $ flightctl app console device/<device_name> --name <vm_app_name> --type serial

    An interactive terminal session opens.

    To disconnect from the serial console, press Enter, then immediately type ~. (tilde followed by period) with no other characters in between. If you are connected through an SSH session, use ~~. (double tilde) so the escape sequence reaches the console session instead of the SSH client.

If you encounter issues connecting to the serial console, check the following:

Symptom Resolution

No output in the terminal

The VM guest kernel does not have console=ttyS0 configured. Add console=ttyS0 to the kernel command line in the guest boot configuration.

HTTP 403 error

You do not have get permission on the devices/applications/console resource. Request the required permission from your administrator.

HTTP 409 error

Another serial console session is already active for this VM application, or the device is in a state that prevents console access. Only one serial console session can be open per application at a time. To take over an existing session, use the --force flag: flightctl app console device/<device_name> --name <vm_app_name> --type serial --force. The original session is disconnected when a new session takes over.

HTTP 504 error

Protocol negotiation with the device agent timed out after 60 seconds. The device agent might be unreachable or the VM might still be starting. Wait and try again.