=======================================================================
vbemagic.sh                  README                          2006-06-12

Restore the VBE state of a blanked Linux text console
=======================================================================
Written by Alexander Griesser (matrox@tuxx-home.at)
2006-06-12, Revision 1.0
2008-01-28, Revision 1.1 (see Changelog at the bottom of this README)

Table of contents:
  1. Foreword
  2. Prerequisites
  3. Usage
  4. Installation
  5. Configuration for automatic start at system bootup
  6. Setting up inittab to make it work with hotkeys
  7. Contact Information
  8. ChangeLog


  1. Foreword
-----------------------------------------------------------------------
This script tries to bring the Linux text console back in instances
where it has gone blank when switching from X to the console.

That behaviour usually is caused by buggy drivers for graphics cards,
e.g., the Matrox Parhelia based graphics cards.


  2. Prerequisites
-----------------------------------------------------------------------
You need to have the program "vbetool" installed for this script to
work correctly. Check your distribution for packages, or download it 
here:

http://freshmeat.net/projects/vbetool/ 

This script will only work if you have not configured your system to
use the Framebuffer console device. At least, I don't think it will
work in that case. If I'm wrong about that, please let me know.


  3. Usage
-----------------------------------------------------------------------
You have to run this tool from a Linux console terminal (e.g. ttyX).
Using it in SSH sessions might not work or might produce undefined results.

vbemagic.sh save     -> Saves the VBE-State to /root/vbestate.sav
vbemagic.sh restore  -> Restores the VBE-State

There are also two compatibility commands (start and stop) to make
this script work as runlevel script. The mapping of the two 
compat-switches is as follows:

start -> save
stop  -> restore


  4. Installation
-----------------------------------------------------------------------
Copy this script to any location in your filesystem, making sure that 
it is set executable via chmod, e.g.:

# chmod 755 /path/to/vbemagic.sh

or

# chmod +x /path/to/vbemagic.sh

For the rest of this readme, I'll assume that you installed vbemagic.sh
in the path /root/vbemagic.sh.


  5. Configuration for automatic start at system bootup
-----------------------------------------------------------------------
Using the start and stop compatibility modes, you can directly 
link any runlevel entry to this script. You should do this in the 
single-user runlevel after your console settings have been modified 
the last time (e.g. console font settings, etc.).

On a Debian system, for example, the commands would be:

ln -s /root/vbemagic.sh /etc/rcS.d/S98vbemagic
ln -s /root/vbemagic.sh /etc/rc6.d/K01vbemagic
ln -s /root/vbemagic.sh /etc/rc0.d/K01vbemagic

That will create three symbolic links in the appropriate runlevel 
directories.

You don't need to restore the VBE screen when you reboot or turn off
your computer, I just put the last two lines there in case you want to.

It is a good idea, though, to create the startup link in the rcS.d
directory, so you don't have to think about what to do if your 
configuration ever changes.


  6. Setting up inittab to make it work with hotkeys
-----------------------------------------------------------------------
Because you can't see anything on a blank console, and your 
"blind-typing-skills" could be better, it would be nice to
have a hotkey configured that executes this script if necessary.

The easiest way to do that is to use the predefined ctrl-alt-del 
keystroke combination in inittab (for other keystrokes, please 
have a look at "man inittab").

In your /etc/inittab file, change the line with the ctrlaltdel action
to look like this one:

    ca::ctrlaltdel:/root/vbemagic.sh restore

Of course for this work, you need to have a saved state of the console in
place.


  7. Contact Information
-----------------------------------------------------------------------
If you have any suggestions, bug reports, donations or additions to
make regarding this program, please don't hesitate to contact me:

Name:    Alexander Griesser
E-Mail:  matrox@tuxx-home.at
Website: http://www.tuxx-home.at
   `MGA: http://www.tuxx-home.at/projects/mga
   `MTX: http://www.tuxx-home.at/projects/mtx


  8. ChangeLog
-----------------------------------------------------------------------
1.1 (2008-01-28)
  * Applied a lot of corrections to the README file pointed out by user
    "starcycle" at http://forum.tuxx-home.at
1.0 (2006-06-12)
  * Initial Release