
The Linux XFree86 HOWTO

Eric Steven Raymond

   [1]Thyrsus Enterprises
   
       esr@thyrsus.com
   
   This is version 7.0
   
   Copyright © 2000 by Eric S. Raymond
   
   $Date: 2000/08/21 05:24:54 $
   Revision History
   Revision 7.0 21 August 2000 Revised by: esr
   First DocBook version.
   
   This document describes how to obtain, install, and configure version
   4.0 of the XFree86 version of the X Window System (X11R6) for Linux
   systems. It is a step-by-step guide to configuring XFree86 on your
   system.
     _________________________________________________________________
   
   Table of Contents
   1. [2]Introduction
          
        1.1. [3]Other sources of information
        1.2. [4]New versions of this document
        1.3. [5]Feedback and Corrections
                
   2. [6]Hardware requirements
   3. [7]Installing XFree86
   4. [8]Configuring XFree86
          
        4.1. [9]Normal Configuration
        4.2. [10]Troubleshooting
        4.3. [11]Custom Configuration
        4.4. [12]Using 16-bit Color
                
   5. [13]Running XFree86
   6. [14]Translations
          
1. Introduction

   The X Window System is a large and powerful (some might say
   excessively large and overly complex) graphics environment for UNIX
   systems. The original X Window System code was developed at MIT;
   commercial vendors have since made X the industry standard for UNIX
   platforms. Virtually every UNIX workstation in the world runs some
   variant of the X Window system.
   
   A freely redistributable port of the MIT X Window System version 11,
   release 6 (X11R6) for 80386/80486/Pentium UNIX systems has been
   developed by a team of programmers originally headed by David
   Wexelblat <[15]dwex@XFree86.org>. The release, known as XFree86, is
   available for System V/386, 386BSD, and other x86 UNIX
   implementations, including Linux. It includes all of the required
   binaries, support files, libraries, and tools.
   
   Complete information on XFree86 is available at the XFree86 web site,
   [16]http://www.XFree86.org.
   
   In this document, we'll give a step-by-step description of how to
   install and configure XFree86 for Linux, but you will have to fill in
   some of the details yourself by reading the documentation released
   with XFree86 itself. (This documentation is discussed below.) However,
   using and customizing the X Window System is far beyond the scope of
   this document---for this purpose you should obtain one of the many
   good books on using the X Window System.
     _________________________________________________________________
   
1.1. Other sources of information

   If you have never heard of Linux before, there are several sources of
   basic information about the system. The best place to find these is at
   the [17]Linux Documentation Project home page. You can find the
   latest, up-to-date version of this document there, as
   [18]http://metalab.unc.edu/LDP/HOWTO/XFree86-HOWTO.html.
     _________________________________________________________________
   
1.2. New versions of this document

   New versions of the Linux XFree86 HOWTO will be periodically posted to
   [19]comp.os.linux.help and [20]comp.os.linux.announce and
   [21]news.answers. They will also be uploaded to various Linux WWW and
   FTP sites, including the LDP home page.
   
   You can always view the latest version of this on the World Wide Web
   via the URL [22]http://metalab.unc.edu/LDP/HOWTO/XFree86-HOWTO.html.
   
   This document was originally written by Matt Welsh in the dim and
   backward abysm of time. Thanks, Matt!
     _________________________________________________________________
   
1.3. Feedback and Corrections

   If you have questions or comments about this document, please feel
   free to mail Eric S. Raymond, at <[23]esr@thyrsus.com>. I welcome any
   suggestions or criticisms. If you find a mistake with this document,
   please let me know so I can correct it in the next version. Thanks.
   
   Please do not mail me questions about how to make your video card and
   monitor work with X. This HOWTO is intended to be a rapid, painless
   guide to normal installation using the new interactive configurator.
   If you run into problems, browse the [24]XFree86 Video Timings HOWTO.
   (This is the up-to-date HTML version of XFree86's `Videomodes.doc'
   file.) That document tells everything I know about configuration
   troubleshooting. If it can't help you, I can't either.
     _________________________________________________________________
   
2. Hardware requirements

   You can find an up-to-date list of supported cards and chipset types
   at [25]the 4.0 status page.
   
   The documentation included with your video adaptor should specify the
   chipset used. If you are in the market for a new video card, or are
   buying a new machine that comes with a video card, have the vendor
   find out exactly what the make, model, and chipset of the video card
   is. This may require the vendor to call technical support on your
   behalf; in general vendors will be happy to do this. Many PC hardware
   vendors will state that the video card is a ``standard SVGA card''
   which ``should work'' on your system. Explain that your software
   (mention Linux and XFree86!) does not support all video chipsets and
   that you must have detailed information.
   
   You can also determine your videocard chipset by running the
   SuperProbe program included with the XFree86 distribution. This is
   covered in more detail below.
   
   Supported video cards will work with all bus types, including ISA and
   VLB and PCI.
   
   One problem faced by the XFree86 developers is that some video card
   manufacturers use non-standard mechanisms for determining clock
   frequencies used to drive the card. Some of these manufacturers either
   don't release specifications describing how to program the card, or
   they require developers to sign a non-disclosure statement to obtain
   the information. This would obviously restrict the free distribution
   of the XFree86 software, something that the XFree86 development team
   is not willing to do. For a long time, this has been a problem with
   certain video cards manufactured by Diamond, but as of release 3.1 of
   XFree86, Diamond has started to work with the development team to
   release free drivers for these cards.
   
   The suggested setup for XFree86 under Linux is a 486 or better with at
   least 8 megabytes of RAM, and a video card with a chipset listed
   above. For optimal performance, we suggest using an accelerated card,
   such as an S3-chipset card. You should check the documentation for
   XFree86 and verify that your particular card is supported before
   taking the plunge and purchasing expensive hardware.
   
   As a side note, the personal Linux system of Matt Welsh (this FAQ's
   originator) was a 486DX2-66, 20 megabytes of RAM, equipped with a VLB
   S3-864 chipset card with 2 megabytes of DRAM. He ran X benchmarks on
   this machine as well as on Sun Sparc IPX workstations. The Linux
   system was roughly 7 times faster than the Sparc IPX (for the curious,
   XFree86-3.1 under Linux, with this video card, runs at around 171,000
   xstones; the Sparc IPX at around 24,000). In general, XFree86 on a
   Linux system with an accelerated SVGA card will give you much greater
   performance than that found on commercial UNIX workstations (which
   usually employ simple framebuffers for graphics).
   
   Your machine will need at least 4 megabytes of physical RAM, and 16
   megabytes of virtual RAM (for example, 8 megs physical and 8 megs
   swap). Remember that the more physical RAM that you have, the less
   that the system will swap to and from disk when memory is low. Because
   swapping is inherently slow (disks are very slow compared to memory),
   having 8 megabytes of RAM or more is necessary to run XFree86
   comfortably. 16 is better. A system with 4 megabytes of physical RAM
   could run much (up to 10 times) more slowly than one with 8 megs or
   more.
     _________________________________________________________________
   
3. Installing XFree86

   It's quite likely that you obtained XFree86 as part of a Linux
   distribution, in which case downloading the software separately is not
   necessary. Or you may be able to get RPM binary packages built for
   your machine, in which case you can just install those using rpm(1).
   In either case you can skip this the rest of this section.
   
   The Linux binary distributions of XFree86 can be found on a number of
   FTP sites. On the XFree86 site they are [26]here. You will want either
   the Linux-axp-glibc21, Linux-ix86-glibc20, or Linux-ix86-glibc21
   subdirectories, depending on your processor type (axp=alpha,
   ix86=Intel 80x86) and Gnu C library version.
   
   Before doing anything else, download and run the `Xinstall.sh' shell
   script first. This may tell you about prerequisites you'll need to
   have in place before continuing your installation. Complete
   instructions for installing the XFree86 nbinary distribution are at
   [27]http://www.xfree86.org/4.0/Install2.html.
   
   The binary directory should contain release notes for the current
   version in RELNOTES. Consult those for installation details.
   
   All that is required to install XFree86 is to obtain the above files,
   create the directory /usr/X11R6 (as root), and unpack the files from
   /usr/X11R6 with a command such as:
gzip -dc Xbin.tgz | tar xfB -

   Remember that these tar files are packed relative to /usr/X11R6, so
   it's important to unpack the files there.
   
   You need to make sure that /usr/X11R6/bin is on your path. This can be
   done by editing your system default /etc/profile or /etc/csh.login
   (based on the shell that you, or other users on your system, use). Or
   you can simply add the directory to your personal path by modifying
   .bashrc or .cshrc, based on your shell.
   
   You also need to make sure that /usr/X11R6/lib can be located by
   ld.so, the runtime linker. To do this, add the line:
/usr/X11R6/lib

   to the file /etc/ld.so.conf, and run /sbin/ldconfig, as root.
     _________________________________________________________________
   
4. Configuring XFree86

4.1. Normal Configuration

   Configuring XFree86 to use your mouse, keyboard, monitor, and video
   card correctly used to be something of a black art, requiring
   extensive hand-hacking of a complex configuration file. No more;
   recent releases have made the process nearly trivial. It simplifies
   matters a lot that there are no longer separate servers for different
   kinds of cards, just modules loaded by a common server. All you do to
   configure it is fire up the program XF86Setup.
   
   This program depends on the fact that all new PC hardware these days
   ships with EGA/VGA capable monitors. It invokes the VGA16 server and
   uses it to bring up X in a lowest-common-denominator 640x480 mode.
   Then it runs an interactive program that walks you through a series of
   five configuration panels -- mouse, keyboard, (video) card, monitor,
   and `other' (miscellaneous server options). The whole process is quite
   painless.
   
   (If you're running Red Hat or Debian Linux, you may see a different
   program called xf86config. This works fairly similarly to XF86Setup
   but does not itself use an X interface and the VGA16 server.)
   
   One minor point to keep in mind is that, if you're like most people
   using a current PC, your keyboard is actually what XF86Setup calls
   `Generic 102-key PC (intl)' rather than the default `Generic 101-key
   PC'. If you pick the default (101) the key cluster on the extreme
   right of your keyboard (numeric keypad and friends) may stop working.
   
   If you're not sure of your monitor type, you can try the listed ones
   in succession. Work your way from top down (upper choices involve
   lower dot-clock speeds and are less demanding on the hardware). Back
   off if you get hash or a seriously distorted picture. Minor
   distortions (picture slightly too large, slightly too small, or
   slightly off-center) are no problem; you'll get a chance to correct
   those immediately by fine-tuning the mode.
   
   And, when the program brings up xvidtune to allow you to tweak your
   video mode, don't let the initial warning box make you nervous. Modern
   multisync monitors (unlike their fixed-frequency predecessors) are not
   easy to damage this way.
   
   XF86Config may assume that your mouse device is /dev/mouse. If you
   find this doesn't work, you may need to link /dev/mouse to whatever
   /dev/ca[01] the mouse is on. If you find that XFree86 gives you a
   "mouse busy" error when gpm is running, you may need to link to
   /dev/ttyS[01] instead.
   
   The configuration process operates by selecting a server module
   corresponding to to the general type of your video card and
   configuring an XF86Config that the server will read on startup to get
   specific parameters for your installation. The location of XF86Config
   varies depending on your OS, but one place to look for it is /etc/X11.
   
   On older versions of XFree86, XF86Setup links the `X' command directly
   to the chosen server. In recent versions, `X' is instead linked to a
   set-user-id wrapper program called Xwrapper. The idea is that all the
   setuid root stuff gets localized in Xwrapper so the server doesn't
   have to run setuid root.
     _________________________________________________________________
   
4.2. Troubleshooting

   Occasionally, something will not be quite right when you initially
   fire up the X server. This is almost always caused by a problem in
   your configuration file. Usually, the monitor timing values are off,
   or the video card dot clocks set incorrectly. Minor problems can be
   fixed with xvidtune; a really garbled screen usually means you need to
   go back into XF86Setup and choose a less capable monitor type.
   
   If your display seems to roll, or the edges are fuzzy, this is a clear
   indication that the monitor timing values or dot clocks are wrong.
   Also be sure that you are correctly specifying your video card
   chipset, as well as other options for the Device section of
   XF86Config. Be absolutely certain that you are using the right X
   server and that /usr/X11R6/bin/X is a symbolic link to this server.
   
   If all else fails, try to start X ``bare''; that is, use a command
   such as:
X >/tmp/x.out 2>&1

   You can then kill the X server (using the ctrl-alt-backspace key
   combination) and examine the contents of /tmp/x.out. The X server will
   report any warnings or errors -- for example, if your video card
   doesn't have a dot clock corresponding to a mode supported by your
   monitor.
   
   Remember that you can use ctrl-alt-numeric + and ctrl-alt-numeric - to
   switch between the video modes listed on the Modes line of the Screen
   section of XF86Config. If the highest resolution mode doesn't look
   right, try switching to lower resolutions. This will let you know, at
   least, that those parts of your X configuration are working correctly.
   
   Also, check the vertical and horizontal size/hold knobs on your
   monitor. In many cases it is necessary to adjust these when starting
   up X. For example, if the display seems to be shifted slightly to one
   side, you can usually correct this using the monitor controls.
   
   The USENET newsgroup comp.windows.x.i386unix is devoted to discussions
   about XFree86, as is comp.os.linux.x. It might be a good idea to watch
   that newsgroup for postings relating to your video configuration---you
   might run across someone with the same problems as your own.
     _________________________________________________________________
   
4.3. Custom Configuration

   You will need to hand-hack your X configuration to get optimal
   performance if your monitor can support 1600x1200 -- the highest
   canned resolution XF86Setup supports is 1280x1024.
   
   If you want to hand-hack your video configuration for this or any
   other reason, go see the LDP's [28]XFree86 Video Timings HOWTO. (This
   is the up-to-date HTML version of XFree86's `Videomodes.doc' file.)
     _________________________________________________________________
   
4.4. Using 16-bit Color

   By default, X uses 8-bit color depth giving 256 colors. To circumvent
   this restriction, many applications allocate their own colormaps,
   resulting in sudden color jumps when the cursor moves between two
   windows each having a color map of its own. The Arena WWW browser does
   it this way.
   
   If you want to use advanced graphic applications 256 colors may be not
   sufficient. You may need to go to 16-bit color depth (65,536 colors).
   But beware, not all applications will work with 16bit colors.
   
   You can use 16bit color depth with 65K different colors simply by
   starting X with
    startx -- -bpp 16

   or putting
    exec X :0 -bpp 16

   into your .xserverrc file. In order for this to work, however, you
   need to have a
screen

   section in your XF86Config with
    DefaultColorDepth 16

   If you're using xdm, you may need to change the Xservers file, which
   is probably located in /etc/X11/xdm/. A typical configuration has just
   one uncommented line, looking something like
      :0 local /usr/X11R6/bin/X

   Add
-bpp 16

   to the startup options:
      :0 local /usr/X11R6/bin/X -bpp 16

   Also, you'll need to add to the `screen' section of your X
   configuration a Display part with a Depth value of 16. Generally you
   can just duplicate the 8-bit Display section and change the Depth
   field.
   
   More colors makes your video card transfer more data during the same
   time. If your video card cannot cope, then either the resolution has
   or the refresh rate has to be reduced. By default, XFree reduces the
   resolution. If you want to keep the resolution and reduce the refresh
   rate, you must insert a new appropriate Modeline into your XF86Config
   file which defines that resolution with a lower refresh rate. For
   instance replace the old value
Modeline "1024x768"  75  1024 1048 1184 1328 768 771 777 806 -hsync -vsync

   with
Modeline "1024x768"  65  1024 1032 1176 1344 768 771 777 806 -hsync -vsync.

   The magic numbers 75 and 65 are the respective clock rates which you
   find reported by X in your .X.err file. Consult the monitors file in
   the XF86 documentation for Modelines suitable to the maximum clock
   rate your video card can deliver under 16bit color depth.
     _________________________________________________________________
   
5. Running XFree86

   With your XF86Config file configured, you're ready to fire up the X
   server and give it a spin. First, be sure that /usr/X11R6/bin is on
   your path.
   
   The command to start up XFree86 is
startx

   This is a front-end to xinit (in case you're used to using xinit on
   other UNIX systems).
   
   This command will start the X server and run the commands found in the
   file .xinitrc in your home directory. .xinitrc is just a shell script
   containing X clients to run. If this file does not exist, the system
   default /usr/X11R6/lib/X11/xinit/xinitrc will be used.
   
   A standard .xinitrc file looks like this:
#!/bin/sh

xterm -fn 7x13bold -geometry 80x32+10+50 &
xterm -fn 9x15bold -geometry 80x34+30-10 &
oclock -geometry 70x70-7+7 &
xsetroot -solid midnightblue &

exec fvwm2

   This script will start up two xterm clients, an oclock, and set the
   root window (background) color to midnightblue. It will then start up
   fvwm2, the window manager. Note that fvwm2 is executed with the
   shell's exec statement; this causes the xinit process to be replaced
   with fvwm2. Once the fvwm2 process exits, the X server will shut down.
   You can cause fvwm2 to exit by using the root menus: depress mouse
   button 1 on the desktop background -- this will display a pop up menu
   which will allow you to Exit Fvwm2.
   
   Be sure that the last command in .xinitrc is started with exec, and
   that it is not placed into the background (no ampersand on the end of
   the line). Otherwise the X server will shut down as soon as it has
   started the clients in the .xinitrc file.
   
   Alternately, you can exit X by pressing ctrl-alt-backspace in
   combination. This will kill the X server directly, exiting the window
   system.
   
   The above is a very, very simple desktop configuration. Many wonderful
   programs and configurations are available with a bit of work on your
   .xinitrc file.
   
   If you are new to the X Window System environment, we strongly suggest
   picking up a book such as The Joy of X: An Overview of the X Window
   System by Niall Mansfield (Addison-Wesley 1993, ISBN 0201-565129).
   Using and configuring X is far too in-depth to cover here. See the man
   pages for xterm, oclock, and fvwm2 for clues on getting started.
     _________________________________________________________________
   
6. Translations

     * [29]Italian
     * [30]Slovenian
     * [31]Croatian
     * [32]Dutch
     * [33]Hungarian

References

   1. http://www.tuxedo.org/~esr/
   2. XFree86-HOWTO.html#AEN29
   3. XFree86-HOWTO.html#AEN37
   4. XFree86-HOWTO.html#AEN42
   5. XFree86-HOWTO.html#AEN51
   6. XFree86-HOWTO.html#AEN59
   7. XFree86-HOWTO.html#AEN72
   8. XFree86-HOWTO.html#AEN102
   9. XFree86-HOWTO.html#AEN104
  10. XFree86-HOWTO.html#AEN129
  11. XFree86-HOWTO.html#AEN147
  12. XFree86-HOWTO.html#AEN152
  13. XFree86-HOWTO.html#AEN176
  14. XFree86-HOWTO.html#AEN218
  15. mailto:dwex@XFree86.org
  16. http://www.XFree86.org/
  17. http://metalab.unc.edu/LDP
  18. http://metalab.unc.edu/LDP/HOWTO/XFree86-HOWTO.html
  19. news:comp.os.linux.help
  20. news:comp.os.linux.announce
  21. news:news.answers
  22. http://metalab.unc.edu/LDP/HOWTO/XFree86-HOWTO.html
  23. mailto:esr@thyrsus.com
  24. http://metalab.unc.edu/LDP/HOWTO/XFree86-Video-Timings-HOWTO.html
  25. http://www.xfree86.org/4.0/Status.html
  26. ftp://ftp.xfree86.org/pub/XFree86/current/binaries/
  27. http://www.xfree86.org/4.0/Install2.html
  28. http://metalab.unc.edu/LDP/HOWTO/XFree86-Video-Timings-HOWTO.html
  29. http://www.pluto.linux.it/ildp/HOWTO/XFree86-HOWTO.html
  30. http://www.lugos.si/delo/slo/HOWTO-sl/XFree86-HOWTO-sl.html
  31. http://meta.mioc.hr/XFree86-KAKO.html
  32. http://www.nl.linux.org/doc/HOWTO/
  33. http://www.ppk.ini.hu/texts/XFree86-HOGYAN/XFree86-HOGYAN.html
