Setting up XFree86 is not difficult in most cases. However, if you happen to be using hardware for which drivers are under development, or wish to obtain the best performance or resolution from an accelerated graphics card, configuring XFree86 can be somewhat time-consuming.
In this section, we describe how to create and edit the
XF86Config
file, which configures the XFree86
server. This file is located in /etc/X11/
in the
current version of XFree86, but in /etc/
in the
previous versions. Also, the file format has changed between Version
3 and Version 4; what we describe here applies to Version 4, the
current version (to make things worse, some Red Hat versions call
this file XF86Config-4
). In many cases, it is
best to start out with a “basic”
XFree86 configuration — one that uses a low resolution. A good
choice is 640x480, which should be supported on all video cards and
monitor types. Once you have XFree86 working at a lower, standard
resolution, you can tweak the configuration to exploit the
capabilities of your video hardware. The idea is that you want to
make sure XFree86 works at least minimally on your system and that
something isn’t wrong with your installation before
attempting the sometimes difficult task of setting up XFree86 for
real use. With current hardware, you should easily be able to get up
to 1024x768 pixels.
But before you start to write an XF86Config
file
yourself, try one of the configuration programs that are available.
In many cases, you can avoid going through the hassle that will be
described on the next pages. Some programs that may help you are:
Some distributions also have their own configuration tools. For example, SuSE has SaX2 and Red Hat has Xconfigurator. These tools are usually very convenient and should be your first try. But if these fail, it is good to know that you have other options at your disposal. Most installation programs start these programs automatically during the installation, but if you configure your X server after installation, you should be able to start them by invoking their name on the command line. When in doubt, consult the documentation of your distribution.
This graphical configuration program is, like xf86config described later, provided by the XFree86 team. It starts up a minimal X server (which is quite sure to run on just about any display hardware) and then lets you select your graphics board, your monitor type, your mouse type, and other options. At the end, it tries to start up a server as configured, and if you are satisfied, it offers to write the configuration file for you. We have found this program to be very useful and reliable in many cases.
-configure
optionIf you run
XFree86 -configure
as root the X server will try to
probe as much information as possible about your hardware and write a
suitable XF86Config
file to
/root/XF86Config.new
(i.e., it
doesn’t overwrite your old configuration file, if
any). In order to try this configuration, you can run the X server
manually with:
XFree86 -xf86config /root/XF86Config.new
which will use the freshly generated configuration file instead of the default one.
This is a text-based configuration program provided by the XFree86
team. It guides you through a set of questions and generates the
XF86Config
file based on your answers. It is not
particularly user-friendly but has been reported to work when the
other options have failed.
If one of these tools is able to configure your X server for you, you
should use it and save yourself a lot of trouble. However, if all the
tools fail or if you want to fine-tune your X server, you will have
to know how to edit the XF86Config
file
yourself.
In addition to the information here, you should read the following documentation:
The XFree86 documentation in
/usr/X11R6/lib/X11/doc
(contained within the
Xdoc
package).
The README
file for your video chipset, if one
exists, in the directory /usr/X11R6/lib/X11/doc
.
These README
files have names, such as
README.i740
and
README.cyrix
.
The manual page for XFree86
.
The manual page for XF86Config
.
The main configuration file you need to create is
/etc/X11/XF86Config
(/etc/XF86Config
in older versions). This file
contains information on your mouse, video card parameters, and so on.
The file XF86Config.eg
is provided with the
XFree86 distribution as an example. Copy this file to
XF86Config
and edit it as a starting point.
The XF86Config
manual page explains the format
of this file in detail. Read this manual page now if you have not
done so already.
We are going to present a sample XF86Config
file, piece by piece. This file may not look exactly like the sample
file included in the XFree86 distribution, but the structure is the
same. The XF86Config
file format may change with
each version of XFree86; this information is valid only for XFree86
Version 4.2.0.
Whatever you do, you should not simply copy the configuration file
listed here to your own system and attempt to use it. Attempting to
use a configuration file that doesn’t correspond to
your hardware could drive the monitor at a frequency that is too high
for it; there have been reports of monitors (especially
fixed-frequency monitors) being damaged or destroyed by using an
incorrectly configured XF86Config
file. The
bottom line is this: make absolutely sure your
XF86Config
file corresponds to your hardware
before you attempt to use it.
Now that we have written this warning, we would also like to mention that configuring XFree86 is much less dangerous than it used to be a few years ago, since the X server has become very good at detecting unsuitable configurations.
Each section of the XF86Config
file is
surrounded by the pair of lines Section
"
section-name
"
...EndSection
.
The first part of the XF86Config
file is
Files
, which looks like this:
Section "Files" FontPath "/usr/X11R6/lib/X11/fonts/misc:unscaled" FontPath "/usr/X11R6/lib/X11/fonts/Type" RgbPath "/usr/X11R6/lib/X11/rgb" EndSection
There can be many more lines like these. The
RgbPath
line sets the path to the X11R6
RGB color database, and each
FontPath
line sets the path to a directory
containing X11 fonts. In general, you shouldn’t have
to modify these lines; just be sure there is a
FontPath
entry for each font type you have
installed (i.e., for each directory in
/usr/X11R6/lib/X11/fonts
). If you add the string
:unscaled
to a FontPath
, the
fonts from this directory will not be scaled. This is often an
improvement because fonts that are greatly scaled look ugly. In
addition to FontPath
and
RgbPath
, you can also add a
ModulePath
to this section, to point to a
directory with dynamically loaded modules. Those modules are
currently used for some special input devices, as well as the PEX and
XIE extensions.
The next section is ServerFlags
, which specifies
several global flags for the server. This section is often empty or
very small:
Section "ServerFlags" Option "AllowMouseOpenFail" EndSection
Here, we say that we want the X server to start up even if it cannot
find the mouse. For more options, please see the
XF86Config(1)
manual page. Often, options will
be autodetected at server startup, so they don’t
need to be listed here.
The next section is the Module
section, with which
you can dynamically load additional X server modules, such as support
for special hardware or graphics libraries like PEX. Unless you want
to use special modules (which are likely to have their own
documentation), you can leave this section out entirely.
The next sections are InputDevice
. You usually
have at least two, one for the keyboard and one for the mouse. If you
have other input devices, such as a graphics tablet, these will go
into additional sections:
Section "InputDevice" Identifier "Keyboard1" Driver "Keyboard" Option "AutoRepeat" "250 30" Option "XkbRules" "xfree86" Option "XkbModel" "pc105" Option "XkbLayout" "us" EndSection Section "InputDevice" Driver "mouse" Identifier "Mouse[1]" Option "Device" "/dev/mouse" Option "Emulate3Buttons" "on" Option "Emulate3Timeout" "50" Option "InputFashion" "Mouse" Option "Name" "Autodetection" Option "Protocol" "ps/2" Option "Vendor" "Sysp" EndSection
Again, other options are available as well. The keyboard configurations listed previously are for a U.S. keyboard; for other keyboards you will need to replace them with other lines suitable for your keyboard.
The mouse
section tells the X server where the
mouse is connected (/dev/mouse
in this case,
which is usually a link to the appropriate port, such as
/dev/ttyS0
), what kind of mouse it is (the
"Protocol"
option) and some other operational
details. It is important for the protocol to be right, but the
aforementioned configuration programs should usually find out the
protocol automatically. You can find the list of supported protocols
in /usr/X11R6/lib/X11/doc/README.mouse
.
BusMouse
should be used
for the Logitech busmouse. Note that older Logitech mice that are not
bus mice should use Logitech
, but newer Logitech
mice that are not bus mice use either the
Microsoft
or the Mouseman
protocol. This is a case where the protocol doesn’t
necessarily have anything to do with the make of the mouse.
If you have a modern serial mouse, you could also try specifying
Auto
, which will try to autoselect a mouse driver.
It is easy to check whether you have selected the correct mouse driver once you have started up X; when you move your mouse, the mouse pointer on the screen should follow this movement. If it does this, your setup is very likely to be correct. If it doesn’t, try another driver, and also check whether the device you specified is correct.
The next section of the XF86Config
file is
Device
, which specifies parameters for your video
card. If you have multiple video cards, there will also be multiple
Device
sections.
Section "Device" BoardName "SiS630 GUI Accelerator+3D" BusID "1:0:0" Driver "sis" Identifier "Device[0]" Screen 0 VendorName "SiS" EndSection
The first entry here, BoardName
, is simply a
descriptive name that reminds you which graphics card you have
configured here (important if you have more than one!). Similarly,
VendorName
is a free-form string that has purely
descriptional purposes. Even the Identifier
string
can be picked freely, but needs to match the
Device
strings used in later sections of the
configuration file. It is customary here to use the names
Device"0"
, Device"1"
, and so
on.
BusID
identifies the actual graphics card in terms
of the built-in hardware on the PCI bus.
PCI:1:0:0
, or the shorter
1:0:0
, is usually the right choice if you have
only one choice. If you are unsure about what to put in here, run the
X server as follows:
XFree86 -scanpci
and check the output carefully. At least one graphics card should be contained in the output (probably among other hardware not relevant here). For example, a line like:
(1:0:0) Matrox unknown card (0x19d8) using a Matrox MGA G400 AGP
tells you that you have a Matrox MGA G400 card with an AGP connector installed. The first digits in parentheses are the PCI bus ID, as described earlier.
The Screen
section is mandatory on multihead
graphics cards, which have more than one monitor output. For
single-head graphics cards, always put in 0
here.
Driver
is very important, as it determines the
actual graphics driver to be loaded by the X server. A good way to
find the right driver name is either to use the configuration
programs described earlier or to run the X server like this:
XFree86 -probeonly
This will output information the X server has collected about your hardware, including the driver it thinks it should use.
There are lots of other options you can specify in this file,
including the chipset, the RAMDAC, and other hardware properties, but
the X server is very good at finding these out all by itself, so you
usually don’t have to do that. If you still want to,
check out the driver-specific README
file, which
lists the options and their possible values for that driver.
The next section is
Monitor
, which specifies the characteristics of
your monitor. As with other sections in the
XF86Config
file, there may be more than one
Monitor
section. This is useful if you have
multiple monitors connected to a system, or use the same
XF86Config
file under multiple hardware
configurations. In general, though, you will need only a single
Monitor
section:
Section "Monitor" Option "CalcAlgorithm" "CheckDesktopGeometry" HorizSync 31-65 Identifier "Monitor[0]" ModelName "1024X768@70HZ" VendorName "--> LCD" VertRefresh 58-78 UseModes "Modes[0]" EndSection
The Identifier
line is used to give an arbitrary
name to the Monitor
entry. This can be any string;
you will use it to refer to the Monitor
entry
later in the XF86Config
file.
HorizSync
specifies the valid horizontal sync
frequencies for your monitor in kHz. If you have a multisync monitor,
this can be a range of values (or several comma-separated ranges), as
seen in the Monitor
section. If you have a
fixed-frequency monitor, this will be a list of discrete values, such
as:
HorizSync 31.5, 35.2, 37.9, 35.5, 48.95
Your monitor manual should list these values in the technical specifications section. If you do not have this information, you should contact either the manufacturer or the vendor of your monitor to obtain it. There are other sources of information, as well; they are listed later.
You should be careful with those settings. While the settings
VertRefresh
and HorizSync
(described next) help to make sure that your monitor will not be
destroyed by wrong settings, you won’t be very happy
with your X setup if you get these values wrong. Unsteady pictures,
flickering, or just plain snow can result.
VertRefresh
specifies
the valid vertical refresh rates (or vertical synchronization
frequencies) for your monitor in Hz. Like
HorizSync
, this can be a range or a list of
discrete values; your monitor manual should list them.
HorizSync
and VertRefresh
are
used only to double-check that the monitor resolutions you specify
are in valid ranges. This reduces the chance that you will damage
your monitor by attempting to drive it at a frequency for which it
wasn’t designed.
You can use the ModeLine
and
Mode
directive to specify resolution modes for
your monitor. However, unlike earlier versions of XFree86, this is
not strictly necessary any longer; the Monitor
section shown earlier (which comes from a laptop)
doesn’t have one. Instead, this information is moved
into the following section, Modes
.
The Modes
section, of which there should be one
for every monitor you have configured, lists the various video modes
that the X server should support. An example:
Section "Modes" Identifier "Modes[0]" Modeline "1024x768" 69.35 1024 1040 1216 1400 768 768 778 802 Modeline "1024x768" 79.55 1024 1040 1216 1400 768 768 778 802 Modeline "800x600" 42.43 800 816 928 1072 600 600 610 626 Modeline "800x600" 48.67 800 816 928 1072 600 600 610 626 EndSection
The Identifier
line refers to a name specified in
the Monitor
section. The following
Modeline
lines each specify a video mode. The
format of Modeline
is:
Modelinename
dot-clock
horiz-values
vert-values
name
is an arbitrary string, which you
will use to refer to the resolution mode later in the file.
dot-clock
is the driving clock frequency
or dot clock associated with the resolution
mode. A dot clock is usually specified in MHz and is the rate at
which the video card must send pixels to the monitor at this
resolution. horiz-values
and
vert-values
are four numbers each; they
specify when the electron gun of the monitor should fire and when the
horizontal and vertical sync pulses fire during a sweep across the
screen.
How can you determine the Modeline
values for your
monitor? That’s difficult, especially since a lot of
the documentation files that used to be shipped with XFree86 are no
longer included, probably because they became outdated and
haven’t been updated yet. Your best bet is probably
to use one of the configuration file generators mentioned in the
previous section to get a set of start values and then tweaking these
until you reach a satisfactory setting. For example, if while running
XFree86 the image on the monitor shifts slightly or seems to flicker,
tweak the values little by little to try to fix the image. Exactly
what you need to adjust is difficult to say because it depends a lot
on your actual graphics hardware, but with some experimenting, you
usually get good results. Also, be sure to check the knobs and
controls on the monitor itself! In many cases it is necessary to
change the horizontal or vertical size of the display after starting
up XFree86 in order for the image to be centered and of the
appropriate size. Another option is to use the program
xvidtune (see the manual page for how to use it),
which can help you to get all the numbers for the
modeline
, lets you try your changes, and even
allows you to undo them if you did something wrong.
Also, XFree86 has the so-called VESA monitor
timings built in, so you might get along without a
Modes
section altogether. The
VESA timings are standard values for the
Modeline
that work on most display hardware, at
the expense of not using the individual hardware to its fullest
potential.
Note that the name
argument to
Modeline
(in this case
"640x480"
) is an arbitrary string; the convention
is to name the mode after the resolution, but
name
can be anything that describes the
mode to you.
For each Modeline
used, the server checks that the
specifications for the mode fall within the range of values specified
with HorizSync
and VertRefresh
.
If they do not, the server will complain when you attempt to start up
X (more on this later).
You shouldn’t insert monitor timing values or
Modeline
values for monitors other than the model
you own. If you attempt to drive the monitor at a frequency for which
it was not designed, you can damage or even destroy it.
The next section is Screen
, which specifies the
monitor/video card combination to use for a particular server:
Section "Screen" DefaultDepth 16 SubSection "Display" Depth 15 Modes "800x600" EndSubSection SubSection "Display" Depth 16 Modes "1024x768" EndSubSection SubSection "Display" Depth 24 Modes "800x600" EndSubSection SubSection "Display" Depth 32 Modes "800x600" EndSubSection SubSection "Display" Depth 8 Modes "800x600" EndSubSection Device "Device[0]" Identifier "Screen[0]" Monitor "Monitor[0]" EndSection EndSection
This section ties together device, screen, and monitor definitions and lists the color depths to use with the video modes.
Finally, the section ServerLayout
wraps things up
by defining one actual configuration that consists of one or more
Screen
sections and one or more
InputDevice
sections. If you have a so-called
multihead system (a system with more than one graphics board and one
monitor attached to each, or one of those fancy multihead graphics
boards to which you can connect multiple monitors), this section also
specifies their relative layout. Here is an example:
Section "ServerLayout" Identifier "Layout[all]" InputDevice "Keyboard[0]" "CoreKeyboard" InputDevice "Mouse[1]" "CorePointer" Option "Clone" "off" Option "Xinerama" "off" Screen "Screen[0]" EndSection
There are also other sections, but these are entirely optional and not needed in order to get your X server up and running.