The Linux XFree86 HOWTO
by Eric S. Raymond
v4.3, 26 March 1997
This document describes how to obtain, install, and configure version
3.2 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.
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 <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,
<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 Linux Documentation Project home page at
<http://sunsite.unc.edu/mdw/linux.html>. You can find the latest, up-
to-date version of this document there, as
<http://sunsite.unc.edu/mdw/HOWTO/XFree86-HOWTO.html>
1.2. New versions of this document
New versions of the Linux XFree86 HOWTO will be periodically posted to
comp.os.linux.help and and news.answers <news: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 <http://sunsite.unc.edu/mdw/HOWTO/XFree86-HOWTO.html>.
1.3. Feedback and Corrections
If you have questions or comments about this document, please feel
free to mail Eric S. Raymond, at 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 Hitchiker's Guide to XFree86
Video Timing, <http://www.ccil.org/~esr/xconfig/video-modes.html>.
(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
As of XFree86 version 3.2, released November 1996, the following video
chipsets are supported. 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.
The following standard SVGA chipsets are supported:
� Tseng ET3000, ET4000AX, ET4000/W32, ET6000
� Western Digital/Paradise PVGA1
� Western Digital WD90C00, WD90C10, WD90C11, WD90C24, WD90C30,
WD90C31, WD90C33
� Genoa GVGA
� Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000,
TVGA9000i, TVGA9100B, TVGA9200CX, TVGA9320, TVGA9400CX, TVGA9420,
TGUI9420DGi, TGUI9430DGi, TGUI9440AGi, TGUI9660XGi, TGUI9680
� ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3,
68800-6, 68800AX, 68800LX, 88800GX-C, 88800GX-D, 88800GX-E,
88800GX-F, 88800CX, 264CT, 264ET, 264VT, 264VT2, 264GT
� NCR 77C22, 77C22E, 77C22E+
� Cirrus Logic CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428,
CLGD5429, CLGD5430, CLGD5434, CLGD5436, CLGD5440, CLGD5446,
CLGD5462, CLGD5464, CLGD6205, CLGD6215, CLGD6225, CLGD6235,
CLGD6410, CLGD6412, CLGD6420, CLGD6440
� OAK OTI067, OTI077, OTI087
� Avance Logic ALG2101, ALG2228, ALG2301, ALG2302, ALG2308, ALG2401
� Chips & Technologies 65520, 65530, 65540, 65545, 65520, 65530,
65540, 65545, 65546, 65548, 65550, 65554
� MX MX68000, MX680010
� Video 7/Headland Technologies HT216-32
� SiS 86C201, 86C202, 86C205
� ARK Logic ARK1000PV, ARK1000VL, ARK2000PV, ARK2000MT
� RealTek RTG3106
� Alliance AP6422
� Matrox MGA2064W
� NVidia/SGS Thomson NV1, STG2000
The following SVGA chipsets with accelerated features are also
supported:
� 8514/A (and true clones)
� ATI Mach8, Mach32, Mach64
� Cirrus CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429,
CLGD5430, CLGD5434, CLGD5436, CLGD5440, CGLD5446, CLGD5462,
CLGD5464.
� S3 86C911, 86C924, 86C801, 86C805, 86C805i, 86C928, 86C864, 86C964,
86C732, 86C764, 86C765, 86C868, 86C968, 86C325, 86C988
� Western Digital WD90C31, WD90C33, WD90C24A
� Weitek P9000
� IIT AGX-014, AGX-015, AGX-016
� IBM XGA-2
� Tseng ET4000/W32, ET4000/W32i, ET4000/W32p, ET6000
� Ark Logic ARK1000PV, ARK1000VL, ARK2000PV, ARK2000MT
� MGA2064W
Video cards using these chipsets are supported on all bus types,
including VLB and PCI.
All of the above are supported in both 256 color and monochrome modes,
with the exception of the Avance Logic, MX and Video 7 chipsets, which
are only supported in 256 color mode. If your video card has enough
DRAM installed, many of the above chipsets are supported in 16 and 32
bits-per-pixel mode (specifically, some Mach32, P9000, S3 and Cirrus
boards). The usual configuration is 8 bits per pixel (that is, 256
colors).
The monochrome server also supports generic VGA cards, the Hercules
monochrome card, the Hyundai HGC1280, Sigma LaserView, and Apollo
monochrome cards. On the Compaq AVGA, only 64k of video memory is
supported for the monochrome server, and the GVGA has not been tested
with more than 64k.
This list will undoubtedly expand as time passes. The release notes
for the current version of XFree86 should contain the complete list of
supported video chipsets.
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 machine 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. Benchmark ratings
comparisons for various video cards under XFree86 are posted routinely
to the USENET newsgroups comp.windows.x.i386unix
<news:comp.windows.x.i386unix> and comp.os.linux.x
<news:comp.os.linux.x>.
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. In that case you can skip this section.
The Linux binary distribution of XFree86 can be found on a number of
FTP sites. On the XFree86 site it's at
<ftp://ftp.xfree86.org/pub/XFree86/current/binaries/Linux> (As of the
time of this writing, the current version is 3.2; newer versions are
released periodically).
On sunsite.unc.edu, it will be found in the directory /pub/Linux/X11.
If you are downloading XFree86 directly, this table lists the files in
the XFree86-3.2 distribution.
One of the following servers is required:
X328514.tgz
Server for 8514-based boards.
X32AGX.tgz
Server for AGX-based boards.
X32I128.tgz
Server for the Number Nine Imagine 128.
X32Mach32.tgz
Server for Mach32-based boards.
X32Mach64.tgz
Server for Mach64-based boards.
X32Mach8.tgz
Server for Mach8-based boards.
X32Mono.tgz
Server for monochrome video modes.
X32P9K.tgz
Server for P9000-based boards.
X32S3.tgz
Server for S3-based boards.
X32S3V.tgz
Server for the S3 ViRGE and ViRGE/VX (considered beta)
X32SVGA.tgz
Server for Super VGA-based boards.
X32W32.tgz
Server for ET4000/W32-based boards.
If you don't know which one to take, take the VGA16 server,
X32VGA16.tgz. You want to download this one anyway, because you'll
need it to run the auto-configuration utility in the next step.
All of the following files are required:
preinst.sh
Pre-installation script
postinst.sh
Post-installation script
X32bin.tgz
The rest of the X11R6 binaries.
X32cfg.tgz
Config files for xdm, xinit and fs.
X32doc.tgz
Documentation and manpages.
X32fnts.tgz
75dpi, misc and PEX fonts
X32lib.tgz
Shared X libraries and support files.
X32set.tgz
XF86Setup utility
X32VG16.tgz
Server for VGA/EGA-based boards.
The following files are optional:
X32f100.tgz
100dpi fonts
X32fcyr.tgz
Cyrillic fonts
X32fnon.tgz
Other fonts (Chinese, Japanese, Korean, Hebrew)
X32fscl.tgz
Scalable fonts (Speedo and Type1)
X32fsrv.tgz
Font server and config files
X32prog.tgz
X header files, config files and compile-time libs
X32lkit.tgz
X server LinkKit
X32lk98.tgz
PC98 X server LinkKit
X32nest.tgz
Nested X server
X32vfb.tgz
Virtual framebuffer X server
X32ps.tgz
PostScript version of the documentation
X32html.tgz
HTML version of the documentation
The XFree86 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 X32bin.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
/etc/.bashrc or /etc/.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.
Note: I found that, after installing all of the following parts:
X32Ma64.tar X32cfg.tar X32fnts.tar X32html.tar X32prog.tar
X32VG16.tar X32doc.tar X32fscl.tar X32lib.tar X32set.tar
X32bin.tar X32f100.tar X32fsrv.tar X32man.tar
that the Xpm support wasn't included in any of them (this is a problem
because the X server itself requires Xpm, at lease in my
configuration; your mileage may vary). I haad to copy the Xpm
libraries from my old X distribution. So the packaging isn't perfect
yet.
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; the
3.2 release has made the process nearly trivial. All you do 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 SVGA16 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.
One minor point to keep in mind is that, if you're like most people
using 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.
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 com�
bination) 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 Hitchiker's Guide to XFree86 Video Timing,
<http://www.ccil.org/~esr/xconfig/video-modes.html>. (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 givibbg 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 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. But beware, not all applications will work
with 16bit colors.
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 twm
This script will start up two xterm clients, an oclock, and set the
root window (background) color to midnightblue. It will then start up
twm, the window manager. Note that twm is executed with the shell's
exec statement; this causes the xinit process to be replaced with twm.
Once the twm process exits, the X server will shut down. You can cause
twm 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 Twm.
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. For example, the fvwm window manager will provide a
virtual desktop, and you can customize colors, fonts, window sizes and
positions, and so forth to your heart's content.
If you are new to the X Window System environment, we strongly suggest
picking up a book such as The X Window System: A User's Guide. Using
and configuring X is far too in-depth to cover here. See the man pages
for xterm, oclock, and twm for clues on getting started.
5.1. Terms of Use
This document is copyright 1996 by Eric S. Raymond. You may use,
disseminate, and reproduce it freely, provided you:
� Do not omit or alter this copyright notice.
� Do not omit or alter or omit the version number and date.
� Do not omit or alter the document's pointer to the current WWW
version.
� Clearly mark any consdensed, altered or versions as such.
These restrictions are intended to protect potential readers from
stale or mangled versions. If you think you have a good case for an
exception, ask me.
5.2. Acknowledgements
This document was originated by Matt Welsh in the dim and backward
abysm of time. Thanks, Matt!