[Home]  [Links]  [grouch] 

Configuring XFree86 in Linux

[Your mileage may vary. Standard disclaimers apply. Do not attempt this while operating heavy machinery.]

See the home of the XFree86 project ( http://xfree86.org ) for authoritative answers.

Configuration procedures that work for me:
[ XFree86 version 3.x ] [ XFree86 version 4.x ]

To determine your installed version of XFree86:

you@yourhost:~$ X -version

XFree86 Version 4.2.1 (Debian 4.2.1-3 20021016191246 branden@deadbeast.net) / X
Window System
(protocol Version 11, revision 0, vendor release 6600)
Release Date: 3 September 2002
        If the server is older than 6-12 months, or if your card is
        newer than the above date, look for a newer version before
        reporting problems.  (See http://www.XFree86.Org/)
Build Operating System: Linux 2.4.18 i686 [ELF]
Module Loader present



  1. Make a backup copy of your existing XF86Config, which should be in the /etc/X11/ directory.
    cp /etc/X11/XF86Config /etc/X11/XF86Config.backup
    You could add the date to the name of that backup file.
  2. Check for the existence of XF86Setup and the XF86_VGA16 server.
    ls -l /usr/X11R6/bin/XF86Setup
    ls -l /usr/X11R6/bin/XF86_VGA16
    If either or both of these are missing, look on your installation CDROM and install them.
  3. Find out the horizontal and vertical frequency ranges of your monitor. This may come from a manual you received with the monitor or you may have to look it up on the manufacturer's website. A good search engine is http://www.google.com.
  4. As root, run XF86Setup from a virtual console (vc, command prompt). X should not be running. When the program asks if it should use the existing XF86Config as its default, answer 'n'. This causes it to use the ultra-compatible XF86_VGA16 server. It is extremely rare that a video card will not be compatible with this server.
  5. Take your time and work through the various tabbed configuration areas. Do NOT click the 'Done' button until you are finished with all sections that you want to set up.
  6. After you exit XF86Setup, test your new configuration.


Setting up the X Window system in Linux is not the chore it once was. You still need to know something about your hardware to go beyond basic video. It helps if you have the manual for your monitor and video card. This will allow you to get the most from your system. Most distributions come with some kind of simple configuration tool, such as Xconfigurator for Redhat and Mandrake. This runs during installation and asks you a few questions about your video hardware. It then picks one mode that works.

You can customize beyond what Xconfigurator can handle using a couple of tools provided with XFree86. XF86Setup uses a plain 16 color VGA X server ( XF86_VGA16) to provide a graphical configuration tool, while xf86config is plain text. Both of these should be located in the /usr/X11R6/bin directory. (If they are not, take a look on your distribution CDROM(s) and install them.) Either can allow you to set up multiple resolutions, refesh rates, and color depth, depending on what your video hardware can handle and how much you know about it. (If you want to crawl out on the bleeding edge and fiddle with the dark magic of video timing, I suggest you read XFree86-Video-Timings-HOWTO first. It could save your monitor).

Before you begin customizing your display, make a backup copy of your working /etc/X11/XF86Config file. Also take note of which X server is symlinked to /etc/X11/X so that you can return to a working configuration if you get things too far out of shape. These are the things the automagical installation tools don't show you when they're setting things up for the first time. You're expected to do some reading of the docs to learn how to change it if you're dissatisfied with the wizard's choice. It's a bit like Windows in that respect, except the documentation goes right down to the source code of the programs at work.

Arm yourself with the horizontal and vertical frequency ranges of your monitor and the amount of RAM on your video card. XFree86 will most likely detect what chipset your card uses. I suggest you answer "no" when XF86Setup asks if you want to use the existing XF86Config file as a starting point. This will force it to use the ultra-compatible VGA 16 server, just like Windows drops to during installation. If a video card/monitor combination is incompatible with that, throw it away. Have patience, read the help it offers, and examine each 'tab' for settings you may change before you click that done button. "Done" in this case means "done with everything", not just the current settings tab.

You will be able to select multiple resolutions and color depths, according to your hardware capabilities and your preferences. Unless you enjoy cycling through them with ctrl-alt-+, deselect those that you don't anticipate using. For instance, even my old Cirrus Logic 5446 with just 2 MB of RAM was capable of far more resolutions and color depths than I ever use. It's couple to a 15" KDS monitor which makes everything above 800x600 squint-time. I deselected all options except 640x480 at 8bpp (256 color, for fallback), 800x600 x 16bpp ('high' color), and 800x600 x 24 bpp ('true' color, for photos). Another machine with a 3D Fusion card ran the gamut from VGA to ridiculous.

Set it up to suit your tastes and hardware. You can tweak it as much or as little as you like. If you run into troubles you can always go back to your last working configuration. You did make a backup of your last working /etc/X11/XF86Config file, right?



  1. Make a backup of your existing configuration, which is /etc/X11/XF86Config-4 by default. Look first.
  2. As root, run XFree86 -configure to let X probe for your video card, mouse and monitor. If successful, it will give instructions for testing the new, barebones configuration.
  3. Test the bare configuration according to the instructions given by XFree86. This should result in an ugly gray screen with a big X in the middle. Move the mouse to see if the X moves. (If the X doesn't move with the mouse, try making a symlink from /dev/mouse to the device that your mouse is connected to, then repeating step 2 above). Use ctrl alt backspace when you're tired of looking at the gray screen.
  4. Edit the new configuration to add "DefaultDepth" and "Modes" in the "Screen" section, and possibly your monitor's HorizSync and VertRefresh ranges in the "Monitor" section.
  5. Test the edited configuration again. If all is well, copy the new configuration to /etc/X11/XF86Config-4 and test it as a regular (non-root) user by running startx.


XFree86 Version 4.x takes a lot of the aggravation out of configuring the X Window System. (Unfortunately, it seems some distributions of Linux and a surprising number of users, insist on putting the old-style aggravation back into configuration. Try it according to the documentation provided by XFree86.org before resorting to some old, clunky script like xf86config).

If X is working at all for you now, make a backup of your current configuration before creating a new one. Version 4.x uses /etc/X11/XF86Config-4 by default. Check that directory and make a backup of any similarly-named file. It doesn't take that much time or hard drive space and will allow you to at least get back to a working system if you make mistakes.

You will need to use root power for this work, since it is system-wide and hardware-based. If you have your system configured for a graphical login, you will have to kill the X server using ctrl alt backspace to reconfigure X. Some distributions force you to go through this loop several times before finally allowing you to login without starting the X server. (Personal rant: what is so difficult about logging into a plain text console and typing startx?)

After logging in as root and making sure X is not running, issue the command: XFree86 -configure to get X to probe your hardware and produce a barebones configuration file. It will write this new file to /root/XF86Config.new and give instructions onscreen for testing it. Follow those instructions:
XFree86 -xf86config /root/XF86Config.new

You should get a gray screen with a big black X in the middle. If you get something like this:

Fatal server error:
Server is already active for display 0
	If this server is no longer running, remove /tmp/.X0-lock
	and start again.
then X is still running. Use alt ctrl F7 (that's function key F7) to switch to the X session and kill it. Retry the test.

That big X in the middle should move when you move your mouse. If it doesn't, you probably have /dev/mouse symlinked to the wrong device or you have no /dev/mouse and X was unable to detect what device is your mouse. Check for a symlink:

ls -l /dev/mouse

lrwxrwxrwx    1 root     root            5 Dec  3 20:30 /dev/mouse -> psaux
The above indicates that my mouse is connected to /dev/psaux which is the PS/2 port. If you get:
ls -l /dev/mouse

ls: /dev/mouse: No such file or directory
then you can create a symlink such as:
ln -s /dev/psaux /dev/mouse
and try again, from the beginning. See http://www.xfree86.org/4.1.0/mouse.html for documentation on mouse configuration. Substitute your X version for "4.1.0" in that URL.

Please note that XFree86 -configure does not deal with the appearance of your desktop. It configures X to deal with your hardware. You then need to edit the new configuration file for your choice of color depth (bits per pixel) and resolution. Your window manager and/or desktop environment then deals with what gets placed on that display.
That ugly gray screen with a big black X which moves with your mouse means XFree86 -configure was successful.

Use your favorite plain-text editor (vi, emacs, joe, nano, pico, mcedit, whatever you choose -- so long as it deals with just plain text and doesn't try to prettify it with word processing codes) to edit /root/XF86Config.new to add "DefaultDepth" and "Modes". Scroll down in your editor until you find:

Section "Screen"
        Identifier "Screen0"
        Device     "Card0"
        Monitor    "Monitor0"
After that "Monitor0" line will be a list of subsections, each dealing with a single colordepth. You need a line before those subsections to tell X which will be your default colordepth (bits per pixel or bpp).


Section "Screen"
        Identifier "Screen0"
        Device     "Card0"
        Monitor    "Monitor0"
	DefaultDepth	24
(Don't worry about 32 bpp, read the XFree86 documentation to see that setting it for 24 bpp is equivalent).

Scroll down to the subsection matching your chosen DefaultDepth and add a "Modes" line:

        SubSection "Display"
                Depth     24
                Modes   "1024x768"
This tells X what resolution(s) you want at this colordepth. NOTE that you must have sufficient RAM on your video card to support the resolution at that colordepth. A clean, crisp screen depends on (a) a good monitor, (b) a good video card, (c) the right choices for colordepth and resolution which result in a decent refresh rate. Don't blind yourself with a higher resolution than your monitor has pixels to produce, nor higher colordepth than your video card can deal with within your monitor's frequency ranges. See http://peripherals.about.com/library/weekly/aa021798.htm for a good discussion of these relationships.

X can get the monitor frequency ranges automatically from most modern monitors. If it can't, you will need to supply your monitor's horizontal sync and vertical refresh frequency ranges. Get these from the monitor manual or manufacturer.


Section "Monitor"
        Identifier   "Monitor0"
        VendorName   "STC"
        ModelName    "KDS XF-70"
        HorizSync    30.0 - 72.0
        VertRefresh  50.0 - 160.0

Test your new configuration again:
XFree86 -xf86configure /root/XF86Config.new
When all seems well, copy it to the proper place:
cp /root/XF86Config.new /etc/X11/XF86Config-4

Test the configuration as a regular user. If something goes wrong, check the logfile:
less /var/log/XFree86.0.log

More reading: