Ubuntu Wiki

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

• Launchpad Entry: bullet-proof-x

• Packages affected: displayconfig-gtk, gdm, Xorg

See also:

• Xorg7%2e3Integration - Upgrading to Xorg 7.3 and adopting xorg.conf autodetection feature
• DisplayConfigGTK - Adopting GUI Xorg configuration tool

• UnifiedLoginUnlock - Improving login screen consistency and reduce user confusion

• XorgCtrlAltBackspace - Disabling ctrl-alt-backspace to reduce user confusion

Summary

This specification describes a new failsafe mode that will be used if X fails to start up. It will be in a reduced (VESA or VGA) graphics environment, 800x600/256, running a single application (gtk-displayconfig) for configuring the graphics devices.

The goal of this specification is to eliminate the need for users to need to run apt-get reconfigure on the commandline. That approach is confusing and too technical for many users, so moving away from that will solve a key pain point for users.

Release Note

This is a failsafe mode for X that will launch if the /etc/X11/xorg.conf file does not result in a working graphical environment due to an X crash. It can also be invoked manually by specifying 'xforcevesa' via grub's kernel cmdline option, by setting the XORG_FAILSAFE_MODE environment variable to a non-empty string, or by selecting the Failsafe option from the Greeter.

Rationale

Xorg sometimes fails to launch for some users, typically due to failure to detect hardware properly during installation or when the user has changed monitors or graphics cards.

Currently Ubuntu support has the user re-run dpkg-reconfigure, but this is confusing and too technical for many users, who complain about this. So the sooner we can move away from requiring that, the better.

Use Cases

• Annette occasionally gives presentations at work on an old projector, but X fails to start when the projector is connected to her Ubuntu laptop, leaving her at the command prompt. Because of this, she has to move her presentation to someone else's non-Ubuntu laptop, but she'd rather be able to use her own.
• Bob changes his monitor for an older one because his monitor broke. Xorg fails to launch because the 'new' (the older one) monitor fails to work with the frequency configured. Bob want to use the older monitor while his monitor is being repaired.
• Cynthia installs for the first time and everything is properly detected except that the color depth is too high, thus consuming too much memory and preventing X from starting.
• Dustin upgrades his graphics adapter and Xorg fails because of an existing configuration for the previous graphics adapter.

Assumptions

• That most failed-to-detect scenarios involve hardware that supports VESA or VGA modes

Design

GDM Failsafe Server

The failsafe mode will be initiated by gdm if it fails to start X, or if an environment variable or command-line option is passed in. This should also permit forcing vesa mode via the boot parameters.

Failsafe mode runs with administrative permissions since it will likely need to alter the user's xorg.conf. Because of this, the user will need to authenticate. However, care must be taken to ensure the user notices that this is an abnormal situation; the authentication request must not be confused with the standard login screen.

In this mode, the current xorg.conf will be ignored; instead a VESA 800x600/256 configuration will be used. In some (rare) cases, hardware may not support VESA, in which case a VGA/16 mode will be the fallback, or framebuffer if that won't work either. These cases will be tracked by means of a blacklist file.

When launched into failsafe mode, a single application will be presented to the user: gtk-displayconfig. A window manager will be needed since gtk-displayconfig has some popup dialogs, but even a simple window manager should suffice. This application will provide several functionalities:

• Help screen
  • Explain why we're in failsafe mode
  • Synopsis of how to use gtk-displayconfig to get out of this mode
  • Where to get further information
  • i18n / translatable
• Skip configuration (Just run X in reduced (VESA) mode)
  • [ ] Never prompt for reconfiguring
• Specify graphics card, monitor, and driver(s)
• Select resolution and refresh rate
• Write out xorg.conf with new changes
  • Use temporarily (just this session)
  • Use as the permanent default

KDM Failsafe Server

KDM currently does not support a failsafe server as GDM does, so support for this capability on KDM-based distros will be deferred until this has been implemented. Assuming a design similar to GDM is adopted, the above design can be used here as well.

Live CD

The above failsafe mode won't be used on the Live CD for Gutsy. If there is an Xorg startup failure when running the live-cd, then it should directly go to vesa mode without requiring any configuration step.

Implementation

1. Create shell script for gdm to run if the X server crashes
   • /etc/gdm/failsafeXServer
2. In /etc/gdm/gdm.conf indicate this failsafe server
   • FailsafeXServer=/etc/gdm/failsafeXServer

     AlwaysRestartServer=true # Maybe, only if GDM isn't forcing a complete X restart

3. Also provide access to the failsafe session via the greeter

   • ShowXtermFailsafeSession=true

4. Configure gdm to also invoke the FailsafeXServer script in any of the following cases:
   • If the previous X session crashed (i.e., gdm never got the signal back from the X server that it started up).
   • Environment variable XORG_FAILSAFE_MODE is defined
   • /proc/cmdline contains option xforcevesa
   • If the user selects the Failsafe option from the chooser
5. When failsafe mode is activated, check the blacklist for systems we know do not support VESA 800x600/256
   • Use EDID + PCI IDs as key to lookup (Can get PCI IDs from discover)
   • If the display does not give EDID info, then use VGA 640x480/16 mode
   • If a matching entry is found, then use VGA 640x480/16 mode
6. Start up the failsafe X session
7. Launch displayconfig-gtk (gnome) or displayconfig (kde) application, under gksu
8. Display a welcome screen explaining why the user is in this mode and what they have to do to solve the issue encountered.
9. Provide a button that allows user to skip configuration and just launch Xorg with the VESA (or VGA) mode.
10. If the user selects the "Never prompt for reconfiguring" option, then set the following in /etc/gdm/gdm.conf:
    • FailsafeXServer=

During fallback mode, should we have a user login or just automatically log them in? Probably have them end up in their regular login, then they can sudo to run setup programs. This should also provide a small subset of the tools - displayconfig-gtk, restricted driver manager?, (probably not synaptic or terminals...) Button to override and go to login anyway, but also hooks to force / help hardware config scenarios where automation is required.

Test/Demo Plan

Acceptance Testing

1. Install Failsafe X package for testing
2. Reboot and use each available mechanism to force failsafe mode
   • Set environment variable
   • Option specified in /proc/cmdline
   • Failsafe mode selected from chooser
   • Deliberately misconfigured X (mismatched kernel/X drivers, bad resolutions, wrong refresh rates, invalid options, etc.)
3. Check that the /etc/X11/xorg.conf file is not being used
4. Verify screen comes up as 800x600/256
5. Verify mouse and keyboard work properly

   • ... and that the keyboard layout is the same as before. --ColinWatson

6. Verify GUI config tool is running
7. Check that help text and interface is internationalized appropriately
8. Check if displayconfig-gtk identifies the hardware correctly and selects the correct driver
9. Verify the GUI provides the correct listing of resolutions and refresh rates for the selected configuration
10. Verify that the system can drop to lower resolutions such as 640x480.
11. Verify that the system can go to the maximum resolution supported by the hardware
12. Verify that the xorg.conf is written with the options selected through the GUI
13. When writing out the xorg.conf, it must preserve any data that existed beforehand. Ideally, it must preserve formatting of this data as well, so diffs will show only meaningful lines changed.

User Testing

• Check if having to authenticate during failsafe adds too much complexity/confusion for users
• Check if users with really thrashed up systems (glx drivers, wrong/mismatched restricted drivers in kernel, etc.) are able to get into failsafe mode gracefully and clean up their system satisfactorily.
• Check the time required by a novice user to hook up a non-EDID projector, boot into failsafe mode, reconfigure, and launch X with an acceptable resolution. It should not require more than 5-10 min max.

In some cases the color range is mis-detected, preventing xorg to load. Perhaps here we need to detect the amount of video ram available to verify the color depth. Log files report this specific error and may be used to trigger fallback.

Rerun the test with different language settings, selecting different resolutions, and selecting incorrect driver/hardware combinations.

• Test R500 / Radeon X1300 - X1950 hardware - this has had problems with vesa mode in the past, but a patch exists to fix it. Since this is a common kind of hardware, especially for laptops, we need to ensure this patch is included in Gutsy.

Outstanding Issues

These need to be resolved, or at least explicitly deferred to a later phase, before the spec can be approved. --ColinWatson

• Does xrandr have a mechanism for exporting the config, so we can apply changes immediately?
  • May need to write some tools to run xrandr to read this
  • There isn't a tool for writing the changes, but that should be a small tool to make
• If resolution of the failed X configuration requires specification of xorg.conf Options, the user will still need to manually add these, because gtk-displayconfig does not currently provide a list of available Options to select from.

  • Do we think this is widespread? Is it worth specifying that we need to add this to gtk-displayconfig? --ColinWatson

Comments

• What about Kubuntu? Since displayconfig-gtk is a port from KDE, I figure it shouldn't be too hard to support that too. --ColinWatson

  • A pre-requisite to this is to have a gdm-style trigger for going into failsafe mode. I checked with the KDM guys at UDS, and they confirmed it lacks this ability, and it didn't sound likely that it would be added in time for Gutsy, so we may need to defer supporting this for now.

CategorySpec

We will need to replace the current install infrastructure with new one using the xrandr and pci-id list approach... We may need to continue with the current xresprobe/ddcprobe stuff for ISA or older systems, but for most known audience we can expect the xrandr approach to be workable.

• Whitelist for determining when to use xrandr
• Whitelist for determining when to use Compiz