/[gentoo]/xml/htdocs/doc/en/xorg-config.xml
Gentoo

Contents of /xml/htdocs/doc/en/xorg-config.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.36 - (show annotations) (download) (as text)
Sat Jan 2 03:02:40 2010 UTC (4 years, 7 months ago) by nightmorph
Branch: MAIN
Changes since 1.35: +4 -8 lines
File MIME type: application/xml
Latest stable xinit (1.2 and up) no longer install TWM, xterm, or xclock, so don't mention assume they're present

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.35 2009/12/31 01:37:01 nightmorph Exp $ -->
4
5 <guide>
6 <title>The X Server Configuration HOWTO</title>
7
8 <author title="Author">
9 <mail link="swift"/>
10 </author>
11 <author title="Author">
12 <mail link="nightmorph"/>
13 </author>
14
15 <abstract>
16 Xorg is the X Window server which allows users to have a graphical
17 environment at their fingertips. This HOWTO explains what Xorg is, how to
18 install it and what the various configuration options are.
19 </abstract>
20
21 <!-- The content of this document is licensed under the CC-BY-SA license -->
22 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23 <license/>
24
25 <version>1.26</version>
26 <date>2010-01-01</date>
27
28 <chapter>
29 <title>What is the X Window Server?</title>
30 <section>
31 <title>Graphical vs Command-Line</title>
32 <body>
33
34 <p>
35 The average user may be frightened at the thought of having to type in commands.
36 Why wouldn't he be able to point and click his way through the freedom provided
37 by Gentoo (and Linux in general)? Well, *big smile*, of course you are able to
38 do this. :-) Linux offers a wide variety of flashy user interfaces and
39 environments which you can install on top of your existing installation.
40 </p>
41
42 <p>
43 This is one of the biggest surprises new users come across: a graphical user
44 interface is nothing more than an application which runs on your system. It is
45 <e>not</e> part of the Linux kernel or any other internals of the system. It is
46 a powerful tool that fully enables the graphical abilities of your workstation.
47 </p>
48
49 <p>
50 As standards are important, a standard for drawing and moving windows on a
51 screen, interacting with the user through mouse, keyboard and other basic, yet
52 important aspects has been created and named the <e>X Window System</e>,
53 commonly abbreviated as <e>X11</e> or just <e>X</e>. It is used on Unix, Linux
54 and Unix-like operating systems throughout the world.
55 </p>
56
57 <p>
58 The application that provides Linux users with the ability to run graphical
59 user interfaces and that uses the X11 standard is Xorg-X11, a fork of
60 the XFree86 project. XFree86 has decided to use a license that might not be
61 compatible with the GPL license; the use of Xorg is therefore recommended.
62 The official Portage tree does not provide an XFree86 package anymore.
63 </p>
64
65 </body>
66 </section>
67 <section>
68 <title>The X.org Project</title>
69 <body>
70
71 <p>
72 The <uri link="http://www.x.org">X.org</uri> project created and
73 maintains a freely redistributable, open-source implementation of the X11
74 system. It is an open source X11-based desktop infrastructure.
75 </p>
76
77 <p>
78 Xorg provides an interface between your hardware and the graphical software
79 you want to run. Besides that, Xorg is also fully network-aware, meaning you
80 are able to run an application on one system while viewing it on a different
81 one.
82 </p>
83
84 </body>
85 </section>
86 </chapter>
87
88 <chapter>
89 <title>Installing Xorg</title>
90 <section>
91 <title>Kernel configuration</title>
92 <body>
93
94 <p>
95 By default, Xorg uses <c>evdev</c>, a generic input driver. You'll need to
96 activate support for <c>evdev</c> by making a change to your kernel
97 configuration. (Read the
98 <uri link="/doc/en/kernel-config.xml">Kernel Configuration Guide</uri> if you
99 don't know how to setup your kernel.)
100 </p>
101
102 <pre caption="Enabling evdev in the kernel">
103 Device Drivers ---&gt;
104 Input device support ---&gt;
105 &lt;*&gt; Event interface
106 </pre>
107
108 </body>
109 </section>
110 <section>
111 <title>make.conf configuration</title>
112 <body>
113
114 <p>
115 Before you install Xorg, you have to configure two important variables in the
116 <path>/etc/make.conf</path> file.
117 </p>
118
119 <p>
120 The first variable is <c>VIDEO_CARDS</c>. This is used to set the video drivers
121 that you intend to use and is usually based on the kind and brand of card you
122 have. The most common settings are <c>nvidia</c> for Nvidia cards or
123 <c>fglrx</c> for ATI Radeon cards. Those are the proprietary drivers from Nvidia
124 and ATI respectively. If you would like to use the open source nVidia driver,
125 use <c>nv</c> rather than <c>nvidia</c> in the variable, but bear in mind that
126 using this driver means no 3D acceleration at all. The free <c>radeon</c> and
127 <c>radeonhd</c> drivers are available for ATI cards, and are more or less the
128 equal of the proprietary <c>fglrx</c> driver. The <c>intel</c> driver may be
129 used for desktops or laptops with common Intel integrated graphics chipsets.
130 <c>VIDEO_CARDS</c> may contain more than one driver, in this case list of them
131 should be separated with spaces.
132 </p>
133
134 <p>
135 The second variable is <c>INPUT_DEVICES</c> and is used to determine which
136 drivers are to be built for input devices. In most cases setting it to
137 <c>evdev</c> should work just fine. If you use alternative input
138 devices, such as a Synaptics touchpad for a laptop, be sure to add it to
139 <c>INPUT_DEVICES</c>.
140 </p>
141
142 <p>
143 Now you should decide which drivers you will use and add necessary settings to
144 the <path>/etc/make.conf</path> file:
145 </p>
146
147 <pre caption="Sample make.conf entries">
148 <comment>(For mouse, keyboard, and Synaptics touchpad support)</comment>
149 INPUT_DEVICES="evdev synaptics"
150 <comment>(For Nvidia cards)</comment>
151 VIDEO_CARDS="nvidia"
152 <comment>(OR, for ATI Radeon cards)</comment>
153 VIDEO_CARDS="radeon"
154 </pre>
155
156 <note>
157 More instructions on how to configure nVidia and ATI cards can be found in the
158 <uri link="/doc/en/nvidia-guide.xml">Gentoo Linux nVidia Guide</uri> and in the
159 <uri link="/doc/en/ati-faq.xml">Gentoo Linux ATI FAQ</uri>. If you don't know
160 which drivers you should choose, refer to these guides for more information.
161 </note>
162
163 <p>
164 If the suggested settings don't work for you, you should run <c>emerge -pv
165 xorg-server</c>, check all the options available and choose those which apply to
166 your system. This example is for a system with a keyboard, mouse, Synaptics
167 touchpad, and a Radeon video card.
168 </p>
169
170 <pre caption="Displaying all the driver options available">
171 # <i>emerge -pv xorg-server</i>
172
173 These are the packages that would be merged, in order:
174
175 Calculating dependencies... done!
176 [ebuild R ] x11-base/xorg-server-1.6.3.901-r2 USE="hal nptl xorg -debug
177 -dmx -ipv6 -kdrive -minimal -sdl -tslib" 0 kB
178 [ebuild R ] x11-base/xorg-drivers-1.6 INPUT_DEVICES="evdev synaptics
179 -acecad -aiptek -citron -elographics -fpit -hyperpen -joystick -keyboard -mouse
180 -mutouch -penmount -tslib -virtualbox -vmmouse -void -wacom"
181 VIDEO_CARDS="radeon -apm -ark -ast -chips -cirrus -dummy -epson -fbdev -fglrx
182 (-geode) -glint -i128 (-i740) (-impact) (-imstt) -intel -mach64 -mga -neomagic
183 (-newport) -nv -nvidia -r128 -radeonhd -rendition -s3 -s3virge -savage
184 -siliconmotion -sis -sisusb (-sunbw2) (-suncg14) (-suncg3) (-suncg6) (-sunffb)
185 (-sunleo) (-suntcx) -tdfx -tga -trident -tseng -v4l (-vermilion) -vesa -via
186 -virtualbox -vmware (-voodoo) (-xgi)" 0 kB
187 </pre>
188
189 <p>
190 After setting all the necessary variables you can install the Xorg package.
191 </p>
192
193 <pre caption="Installing Xorg">
194 # <i>emerge xorg-server</i>
195 </pre>
196
197 <note>
198 You could install the <c>xorg-x11</c> metapackage instead of the more
199 lightweight <c>xorg-server</c>. Functionally, <c>xorg-x11</c> and
200 <c>xorg-server</c> are the same. However, <c>xorg-x11</c> brings in many more
201 packages that you probably don't need, such as a huge assortment of fonts in
202 many different languages. They're not necessary for a working desktop.
203 </note>
204
205 <p>
206 When the installation is finished, you will need to re-initialise some
207 environment variables before you continue. Just run <c>env-update</c> followed
208 by <c>source /etc/profile</c> and you're all set.
209 </p>
210
211 <pre caption="Re-initialising the environment variables">
212 # <i>env-update</i>
213 # <i>source /etc/profile</i>
214 </pre>
215
216 <p>
217 Now it's time to start the Hardware Abstraction Layer (HAL) daemon and set it to
218 automatically start each time you boot. This is necessary to get a working X
219 environment, otherwise your input devices won't be detected and you'll probably
220 just get a blank screen. We'll cover HAL more in the <uri
221 link="#using_hal">next section</uri>.
222 </p>
223
224 <pre caption="Starting HAL">
225 # <i>/etc/init.d/hald start</i>
226 # <i>rc-update add hald default</i>
227 </pre>
228
229 </body>
230 </section>
231 </chapter>
232
233 <chapter>
234 <title>Configuring Xorg</title>
235 <section id="using_hal">
236 <title>Using HAL</title>
237 <body>
238
239 <p>
240 Recent X server versions are designed to work out-of-the-box, with no need to
241 manually edit Xorg's configuration files.
242 </p>
243
244 <p>
245 You should first try <uri link="#using_startx">starting X</uri> without creating
246 <path>/etc/X11/xorg.conf</path>.
247 </p>
248
249 <p>
250 If Xorg won't start (if there's something wrong with the screen, or with your
251 keyboard/mouse), then you can try fixing problems by using the right
252 configuration files.
253 </p>
254
255 <p>
256 By default, Xorg uses HAL (Hardware Abstraction Layer) to detect and configure
257 devices such as keyboards and mice.
258 </p>
259
260 <p>
261 HAL comes with many premade device rules, also called policies. These policy
262 files are available in <path>/usr/share/hal/fdi/policy/</path>. Just find a few
263 that suit your needs most closely and copy them to
264 <path>/etc/hal/fdi/policy/</path>.
265 </p>
266
267 <impo>
268 Do not edit the files in <path>/usr/share/hal/fdi/</path>! Just copy the ones
269 you need, and edit them once they're placed in the proper <path>/etc</path>
270 location.
271 </impo>
272
273 <p>
274 For example, to get a basic working keyboard/mouse combination, you could copy
275 the following files to <path>/etc/hal/fdi/policy/</path>:
276 </p>
277
278 <pre caption="Using HAL policy files">
279 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-input-policy.fdi /etc/hal/fdi/policy</i>
280 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-x11-input.fdi /etc/hal/fdi/policy</i>
281 </pre>
282
283 <p>
284 There are several other HAL policies in <path>/usr/share/hal/fdi/</path> that
285 may interest you, such as laptop configurations, storage device handling, power
286 management, and more. Just copy any of the policies to
287 <path>/etc/hal/fdi/policy/</path>.
288 </p>
289
290 <impo>
291 Remember, <e>every</e> time you finish making changes to HAL policy files, you
292 need to restart the HAL daemon by running <c>/etc/init.d/hald restart</c>.
293 </impo>
294
295 <p>
296 You can edit the policy files in <path>/etc/hal/fdi/policy</path> to your
297 liking. You may want to make a few tweaks or to expose additional
298 functionality. Let's go through an example of tweaking a HAL policy.
299 </p>
300
301 <p>
302 One very convenient trick is to kill the X server entirely by pressing
303 Ctrl-Alt-Backspace. This is useful when your X server is malfunctioning, frozen,
304 etc. It's not as extreme as rebooting the whole machine with Ctrl-Alt-Del.
305 </p>
306
307 <p>
308 Recent X server versions disabled this key combination by default. However, you
309 can reenable it by copying <path>10-x11-input.fdi</path> to
310 <path>/etc/hal/fdi/policy</path> and editing it. You'll need to add just one
311 line to the appropriate section, as shown below:
312 </p>
313
314 <pre caption="Editing 10-x11-input.fdi">
315 <comment>(Open the file in your preferred editor)</comment>
316 # <i>nano -w /etc/hal/fdi/policy/10-x11-input.fdi</i>
317 <comment>(Find the "input.keys" section)</comment>
318 &lt;match key="info.capabilities" contains="input.keys"&gt;
319 <comment>(Add the "terminate" merge string as shown)</comment>
320 &lt;match key="info.capabilities" contains="input.keys"&gt;
321 &lt;merge key="input.x11_driver" type="string"&gt;keyboard&lt;/merge&gt;
322 <i>&lt;merge key="input.xkb.options" type="string"&gt;terminate:ctrl_alt_bksp&lt;/merge&gt;</i>
323 &lt;match key="/org/freedesktop/Hal/devices/computer:system.kernel.name"
324 string="Linux"&gt;
325 &lt;merge key="input.x11_driver" type="string"&gt;evdev&lt;merge&gt;
326 &lt;/match&gt;
327 &lt;/match&gt;
328 </pre>
329
330 <p>
331 Once you're done, run <c>/etc/init.d/hald restart</c> so that HAL picks up your
332 changes.
333 </p>
334
335 <p>
336 There, now you have a handy way of killing an unresponsive X server. This is
337 useful when programs have frozen your display entirely, or when configuring and
338 tweaking your Xorg environment. Be careful when killing your desktop with this
339 key combination -- most programs really don't like it when you end them this
340 way, and you may lose some (or all) of what you were working on.
341 </p>
342
343 <p>
344 Hopefully just working with the HAL policy files results in a working X desktop.
345 If Xorg still won't start, or there's some other problem, then you'll need to
346 manually configure <path>xorg.conf</path> as shown in the next section.
347 </p>
348
349 </body>
350 </section>
351 <section>
352 <title>The xorg.conf file</title>
353 <body>
354
355 <note>
356 Configuring <path>xorg.conf</path> should be seen as a "last resort" option. It
357 really desirable to run without one if possible, and to do all your
358 configuration via HAL policy files. If you still can't get a working
359 configuration, then read on.
360 </note>
361
362 <p>
363 The configuration file of Xorg is called <path>xorg.conf</path> and it resides
364 in <path>/etc/X11</path>. Xorg provides an example configuration as
365 <path>/etc/X11/xorg.conf.example</path> which you can use to create your own
366 configuration. It is heavily commented, but if you are in need of more
367 documentation regarding the syntax, don't hesitate to read the man page:
368 </p>
369
370 <pre caption="Reading the xorg.conf man page">
371 $ <i>man 5 xorg.conf</i>
372 </pre>
373
374 </body>
375 </section>
376 <section>
377 <title>Automatic Generation of xorg.conf</title>
378 <body>
379
380 <p>
381 Xorg itself is able to guess most parameters for you. In most cases, you
382 will only have to change some lines to get the resolution you want up and
383 running. If you are interested in more in-depth tweaking, be sure to check the
384 resources at the end of this chapter. But first, let us generate a (hopefully
385 working) Xorg configuration file.
386 </p>
387
388 <pre caption="Generating an xorg.conf file">
389 # <i>Xorg -configure</i>
390 </pre>
391
392 <p>
393 Be sure to read the last lines printed on your screen when Xorg has finished
394 probing your hardware. If it tells you it failed at some point, you're forced to
395 manually write an <path>xorg.conf</path> file. Assuming that it didn't fail, it
396 will have told you that it has written <path>/root/xorg.conf.new</path> ready
397 for you to test. So let's test. :)
398 </p>
399
400 <pre caption="Testing the xorg.conf.new file">
401 # <i>X -config /root/xorg.conf.new</i>
402 </pre>
403
404 <p>
405 If all goes well, you should see a simple black and white pattern. Verify if
406 your mouse works correctly and if the resolution is good. You might not be able
407 to deduce the exact resolution, but you should be able to see if it's too low.
408 You can exit any time by pressing Ctrl-Alt-Backspace.
409 </p>
410
411 </body>
412 </section>
413 <section>
414 <title>Copying over xorg.conf</title>
415 <body>
416
417 <p>
418 Let us copy over the <path>xorg.conf.new</path> to
419 <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run
420 <c>X -config</c> -- typing just <c>startx</c> is easier. :)
421 </p>
422
423 <pre caption="Copying over xorg.conf">
424 # <i>cp /root/xorg.conf.new /etc/X11/xorg.conf</i>
425 </pre>
426
427 </body>
428 </section>
429 <section id="using_startx">
430 <title>Using startx</title>
431 <body>
432
433 <p>
434 Now try <c>startx</c> to start up your X server. <c>startx</c> is a script
435 that executes an <e>X session</e>, that is, it starts the X servers and some
436 graphical applications on top of it. It decides which applications to run
437 using the following logic:
438 </p>
439
440 <ul>
441 <li>
442 If a file named <path>.xinitrc</path> exists in the home directory, it will
443 execute the commands listed there.
444 </li>
445 <li>
446 Otherwise, it will read the value of the XSESSION variable and will execute
447 one of the sessions available in <path>/etc/X11/Sessions/</path>
448 accordingly. You can set the value of XSESSION in
449 <path>/etc/env.d/90xsession</path> to make it a default for all the users on
450 the system. For example, as root, run <c>echo XSESSION="Xfce4" >
451 /etc/env.d/90xsession</c>. This will create the <path>90xsession</path> file
452 and set the default X session to Xfce4.
453 </li>
454 </ul>
455
456 <pre caption="Starting X">
457 # <i>startx</i>
458 </pre>
459
460 <p>
461 You can kill the X session using the Ctrl-Alt-Backspace combination. This will
462 however make X exit disgracefully -- something that you might not always want.
463 </p>
464
465 </body>
466 </section>
467 </chapter>
468
469 <chapter>
470 <title>Tweaking X settings</title>
471 <section>
472 <title>Setting your Resolution</title>
473 <body>
474
475 <p>
476 If you feel that the screen resolution is wrong, you will need to check two
477 sections in your <path>xorg.conf</path> configuration. First of all, you have
478 the <e>Screen</e> section which lists the resolutions, if any that your X server
479 will run at. By default, this section might not list any resolutions at all. If
480 this is the case, Xorg will estimate the resolutions based on the information in
481 the second section, <e>Monitor</e>.
482 </p>
483
484 <p>
485 What happens is that Xorg checks the settings of <c>HorizSync</c> and
486 <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions.
487 For now, leave these settings as-is. Only when the changes to the <e>Screen</e>
488 section (which we will describe in a minute) don't work, then you will need to
489 look up the specs for your monitor and fill in the correct values.
490 </p>
491
492 <warn>
493 Do <b>not</b> "just" change the values of these two monitor related variables
494 without consulting the technical specifications of your monitor. Setting
495 incorrect values lead to out-of-sync errors at best and smoked up screens at
496 worst.
497 </warn>
498
499 <p>
500 Now let us change the resolutions. In the next example from
501 <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the
502 <c>DefaultDepth</c> so that our X server starts with 24 bits at 1440x900 by
503 default. Don't mind the given strings -- they are examples and will most likely
504 differ from the settings on your system.
505 </p>
506
507 <pre caption="Changing the Screen section in /etc/X11/xorg.conf">
508 Section "Screen"
509 Identifier "Default Screen"
510 Device "RadeonHD 4550"
511 Monitor "Generic Monitor"
512 <i>DefaultDepth 24</i>
513 <comment># Skipping some text to improve readability</comment>
514 SubSection "Display"
515 Depth 24
516 <i>Modes "1440x900"</i>
517 EndSubSection
518 EndSection
519 </pre>
520
521 <p>
522 Run X (<c>startx</c>) to discover it uses the resolution you want. :)
523 </p>
524
525 </body>
526 </section>
527 <section>
528 <title>Configuring your keyboard</title>
529 <body>
530
531 <p>
532 To setup X to use an international keyboard, you can copy the content of
533 <path>/usr/share/doc/hal-*/*/use-estonian-layout.fdi.bz2</path> to
534 <path>/etc/hal/fdi/policy/10-xinput-configuration.fdi</path>:
535 </p>
536
537 <pre caption="Using an existing config file">
538 # <i>bzcat /usr/share/doc/hal-*/*/use-estonian-layout.fdi > /etc/hal/fdi/policy/10-xinput-configuration.fdi</i>
539 </pre>
540
541 <p>
542 Now you can just edit <path>10-xinput-configuration.fdi</path> and change the
543 Estonian keyboard layout (<c>ee</c>) to your own, such as Great Britain
544 (<b>gb</b>) or Polish (<b>pl</b>).
545 </p>
546
547 <p>
548 When you're finished, run <c>/etc/init.d/hald restart</c> as root to make sure
549 that HAL picks up your configuration file changes.
550 </p>
551
552 </body>
553 </section>
554 <section>
555 <title>Finishing up</title>
556 <body>
557
558 <p>
559 Run <c>startx</c> and be happy about the result. Congratulations, you now
560 (hopefully) have a working Xorg on your system. The next step is to install a
561 useful window manager (or even a desktop environment) such as KDE or GNOME, but
562 that's not part of this guide.
563 </p>
564
565 </body>
566 </section>
567 </chapter>
568
569 <chapter>
570 <title>Resources</title>
571 <section>
572 <title>Creating and Tweaking xorg.conf</title>
573 <body>
574
575 <p>
576 First of all, <c>man xorg.conf</c> and <c>man evdev</c> provide quick yet
577 complete references about the syntax used by these configuration files. Be sure
578 to have them open on a terminal near you when you edit your configuration
579 files!
580 </p>
581
582 <p>
583 Also, be sure to look at <path>/etc/X11/xorg.conf.example</path>; you may wish
584 to copy this and use it as a foundation for writing your own
585 <path>xorg.conf</path>.
586 </p>
587
588 <p>
589 You may find the X.org <uri link="http://www.x.org/wiki/FAQ">FAQ</uri> provided
590 on their website, in addition to their other documentation.
591 </p>
592
593 <p>
594 There are also many online resources on editing <path>xorg.conf</path>. We only
595 list few of them here, be sure to <uri link="http://www.google.com">Google</uri>
596 for more.
597 </p>
598
599 </body>
600 </section>
601 <section>
602 <title>Other resources</title>
603 <body>
604
605 <p>
606 More information about installing and configuring various graphical desktop
607 environments and applications can be found in the <uri
608 link="/doc/en/?catid=desktop">Gentoo Desktop Documentation Resources</uri>
609 section of our documentation.
610 </p>
611
612 <p>
613 If you're upgrading to xorg-server-1.6 from an earlier version, then be sure to
614 read the <uri
615 link="/proj/en/desktop/x/x11/xorg-server-1.6-upgrade-guide.xml">migration
616 guide</uri>.
617 </p>
618
619 </body>
620 </section>
621 </chapter>
622 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20