Update the paths for xdm example configs and the binary
[ikiwiki.git] / docs / newhandbook / X / index.mdwn
CommitLineData
a86df2f3 1# The X Window System
a86df2f3 2***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz.***
3
ca543863 4[[!toc levels=3]]
5
a86df2f3 6
7## Synopsis
8
8ff68d2e 9This chapter will cover the installation and some configuration of X11. For more information on the video hardware that X11 supports, check the [X.org](http://www.x.org/) web site. If you have problems configuring, just search the web. There are lots of tutorials and guides on how to set up your X properly.
a86df2f3 10
11
8ff68d2e 12Before reading this chapter, you should know how to install additional third-party software. Read the pkgsrc section of the documentation.
a86df2f3 13
a86df2f3 14
15
16
17
18## Understanding X
19
20### The Window Manager
21
22
23
8ff68d2e 24X.org itself does not give you a window manager. You will have to choose one and install it yourself. There are dozens of window managers available for X. Each of these provides a different look and feel. Window managers are available in the `wm` category of the pkgsrc collection.
a86df2f3 25
26
8ff68d2e 27In addition, the **KDE** and **GNOME** desktop environments both have their own window managers which integrate with the desktop.
a86df2f3 28
a86df2f3 29
8ff68d2e 30Every window manager also has a different configuration mechanism. Read your manager's documentation to learn more.
a86df2f3 31
32
33
34
35
36## Installing X
37
5fa36c0a 38**X.org** is currently available in the DragonFly pkgsrc framework.
a86df2f3 39
a86df2f3 40
5fa36c0a 41To install:
a86df2f3 42
110f93fc 43 # cd /usr/pkgsrc/meta-pkgs/modular-xorg
a86df2f3 44 # bmake install clean
45
46
47
5fa36c0a 48
49Alternatively, X11 can be installed directly from pre built packages with [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_radd&section=1). So to fetch and install the package of **X.org**, type:
a86df2f3 50
51
5fa36c0a 52 # pkg_radd modular-xorg
a86df2f3 53
54
5fa36c0a 55**Note:** The examples above will install the complete X11 distribution including the server, drivers, programs, libraries and fonts. Separate packages for everything are available.
a86df2f3 56
57
58
59
60----
61
62
63
64## Configuring X
65
66
67
68 ***Contributed by Christopher Shumway. ***
69
70
71
a86df2f3 72
73
32c109d2 74As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
a86df2f3 75
32c109d2 76
a86df2f3 77
32c109d2 78 % startx
a86df2f3 79
80
81
a86df2f3 82
32c109d2 83If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
a86df2f3 84
32c109d2 85
a86df2f3 86
32c109d2 87 # Xorg -configure
a86df2f3 88
89
32c109d2 90This will generate an X11 configuration skeleton file in the `/root` directory called `xorg.conf.new` (whether you [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) or do a direct login affects the inherited supervisor `$HOME` directory variable). The X11 program will attempt to probe the graphics hardware on the system and write a configuration file to load the proper drivers for the detected hardware on the target system.
a86df2f3 91
a86df2f3 92
93
32c109d2 94The next step is to test the existing configuration to verify that **X.org** can work with the graphics hardware on the target system. To perform this task, type:
a86df2f3 95
32c109d2 96
a86df2f3 97
32c109d2 98 # Xorg -config xorg.conf.new
a86df2f3 99
100
32c109d2 101If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press **Ctrl** + **Alt** + **Backspace** simultaneously.
a86df2f3 102
a86df2f3 103
a86df2f3 104
32c109d2 105**Note:** If the mouse does not work, you will need to first configure it before proceeding. This can usually be achieved by just using `/dev/sysmouse` as the input device in the config file and enabling `moused`:
a86df2f3 106
32c109d2 107 # rcenable moused
a86df2f3 108
a86df2f3 109
110
8ff68d2e 111Tune the `xorg.conf.new` configuration file to taste and move it to where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg&section=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
a86df2f3 112
113
114
a86df2f3 115The X11 configuration process is now complete. You can start **X.org** with [startx(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1). The X11 server may also be started with the use of [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
116
117
a86df2f3 118
119
120## The X Display Manager
121
122 ***Contributed by Seth Kingsley.***
123
124
125
126### Overview
127
128
129
130 The X Display Manager ( **XDM** ) is an optional part of the X Window System that is used for login session management. This is useful for several types of situations, including minimal "X Terminals", desktops, and large network display servers. Since the X Window System is network and protocol independent, there are a wide variety of possible configurations for running X clients and servers on different machines connected by a network. **XDM** provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination.
131
132
133
134 Think of **XDM** as providing the same functionality to the user as the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) utility (see [ Section 17.3.2](term.html#TERM-CONFIG) for details). That is, it performs system logins to the display being connected to and then runs a session manager on behalf of the user (usually an X window manager). **XDM** then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point, **XDM** can display the login and display chooser screens for the next user to login.
135
136
137
138### Using XDM
139
140
141
123315ad 142 The **XDM** daemon program is located in `/usr/pkg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If **XDM** is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the **XDM** daemon on a virtual terminal:
a86df2f3 143
144
145
146
147
123315ad 148 ttyv8 "/usr/pkg/bin/xdm -nodaemon" xterm off secure
a86df2f3 149
150
151
152
153
154 By default this entry is disabled; in order to enable it change field 5 from `off` to `on` and restart [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) using the directions in [ Section 17.3.2.2](term.html#TERM-HUP). The first field, the name of the terminal this program will manage, is `ttyv8`. This means that **XDM** will start running on the 9th virtual terminal.
155
156
157
158### Configuring XDM
159
160
161
123315ad 162 The **XDM** configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xdm/`, in this directory there are several files used to change the behavior and appearance of **XDM** . Typically these files will be found:
a86df2f3 163
164
165[[!table data="""
166<tablestyle="width:100%"> **File** | **Description**
167<tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
168`Xresources` | Default X resource values.
169`Xservers` | List of remote and local displays to manage.
170`Xsession` | Default session script for logins.
171`Xsetup_`* | Script to launch applications before the login interface.
172`xdm-config` | Global configuration for all displays running on this machine.
173`xdm-errors` | Errors generated by the server program.
174`xdm-pid` | The process ID of the currently running XDM. |
175
176"""]]
177
178
179 Also in this directory are a few scripts and programs used to set up the desktop when **XDM** is running. The purpose of each of these files will be briefly described. The exact syntax and usage of all of these files is described in [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
180
181
182
183 The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. This is a good starting point for changing the look and feel of **XDM** screens.
184
185
186
187#### Xaccess
188
189
190
191 The protocol for connecting to **XDM** controlled displays is called the X Display Manager Connection Protocol (XDMCP). This file is a ruleset for controlling XDMCP connections from remote machines. It is ignored unless the `xdm-config` is changed to listen for remote connections. By default, it does not allow any clients to connect.
192
193
194
195#### Xresources
196
197
198
199 This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the X11 documentation.
200
201
202
203#### Xservers
204
205
206
207 This is a list of the remote displays the chooser should provide as choices.
208
209
210
211#### Xsession
212
213
214
215 This is the default session script for **XDM** to run after a user has logged in. Normally each user will have a customized session script in `~/.xsession` that overrides this script.
216
217
218
219#### Xsetup_*
220
221
222
223 These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named `Xsetup_` followed by the local display number (for instance `Xsetup_0`). Typically these scripts will run one or two programs in the background such as `xconsole`.
224
225
226
227#### xdm-config
228
229
230
231 This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
232
233
234
235#### xdm-errors
236
237
238
239 This contains the output of the X servers that **XDM** is trying to run. If a display that **XDM** is trying to start hangs for some reason, this is a good place to look for error messages. These messages are also written to the user's `~/.xsession-errors` file on a per-session basis.
240
241
242
243### Running a Network Display Server
244
245
246
247 In order for other clients to connect to the display server, edit the access control rules, and enable the connection listener. By default these are set to conservative values. To make **XDM** listen for connections, first comment out a line in the `xdm-config` file:
248
249
250
251
252
253 ! SECURITY: do not listen for XDMCP or Chooser requests
254
255 ! Comment out this line if you want to manage X terminals with xdm
256
257 DisplayManager.requestPort: 0
258
259
260
261
262
263 and then restart **XDM** . Remember that comments in app-defaults files begin with a "!" character, not the usual "#". More strict access controls may be desired. Look at the example entries in `Xaccess`, and refer to the [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) manual page for further information.
264
265
266
267### Replacements for XDM
268
269
270
271 Several replacements for the default **XDM** program exist. One of them, **kdm** (bundled with **KDE** ) is described later in this chapter. The **kdm** display manager offers many visual improvements and cosmetic frills, as well as the functionality to allow users to choose their window manager of choice at login time.
272
273
274----
275
276
277
278## Desktop Environments
279
280 ***Contributed by Valentino Vaschetto. ***
281
282 This section describes the different desktop environments available for X on FreeBSD. A ***desktop environment*** can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as **KDE** or **GNOME** .
283
284
285
286### GNOME
287
288
289
290#### About GNOME
291
292
293
294 **GNOME** is a user-friendly desktop environment that enables users to easily use and configure their computers. **GNOME** includes a panel (for starting applications and displaying status), a desktop (where data and applications can be placed), a set of standard desktop tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. Users of other operating systems or environments should feel right at home using the powerful graphics-driven environment that **GNOME** provides.
295
296
297
298#### Installing GNOME
299
300
301
302 **GNOME** can be easily installed from a package or from the pkgsrc framework:
303
304
305
306 To install the **GNOME** package from the network, simply type:
307
308 # pkg_radd gnome
309
310
311
312
313
314 To build **GNOME** from source, use the ports tree:
315
316
317
318 # cd /usr/pkgsrc/meta-pkgs/gnome
319
320 # bmake install clean
321
322
323
324 Once **GNOME** is installed, the X server must be told to start **GNOME** instead of a default window manager.
325
326
327
328 The easiest way to start **GNOME** is with **GDM** , the GNOME Display Manager. **GDM** , which is installed as a part of the **GNOME** desktop (but is disabled by default), can be enabled by adding `gdm_enable="YES"` to `/etc/rc.conf`. Once you have rebooted, **GNOME** will start automatically once you log in -- no further configuration is necessary.
329
330
331
332**GNOME** may also be started from the command-line by properly configuring a file named `.xinitrc`. If a custom `.xinitrc` is already in place, simply replace the line that starts the current window manager with one that starts **/usr/pkg/bin/gnome-session** instead. If nothing special has been done to the configuration file, then it is enough simply to type:
333
334
335
336
337
338 % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
339
340
341
342
343
344 Next, type `startx`, and the **GNOME** desktop environment will be started.
345
346
347**Note:** If an older display manager, like **XDM** , is being used, this will not work. Instead, create an executable `.xsession` file with the same command in it. To do this, edit the file and replace the existing window manager command with **/usr/pkg/bin/gnome-session** :
348
349
350
351
352
353 % echo "#!/bin/sh" > ~/.xsession
354
355 % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
356
357 % chmod +x ~/.xsession
358
359
360
361
362
363 Yet another option is to configure the display manager to allow choosing the window manager at login time; the section on [ KDE details](x11-wm.html#X11-WM-KDE-DETAILS) explains how to do this for **kdm** , the display manager of **KDE** .
364
365
366
367#### Anti-aliased Fonts with GNOME
368
369
370
371 X11 supports anti-aliasing via its ***RENDER*** extension. GTK+ 2.0 and greater (the toolkit used by **GNOME** ) can make use of this functionality. Configuring anti-aliasing is described in [ Section 5.5.3](x-fonts.html#ANTIALIAS).
372
373 So, with up-to-date software, anti-aliasing is possible within the **GNOME** desktop. Just go to **Applications->Desktop Preferences->Font** , and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the **GNOME** desktop, set the environment variable `GDK_USE_XFT` to `1` before launching the program.
374
375
376
377### KDE
378
379
380
381#### About KDE
382
383
384
385 **KDE** is an easy to use contemporary desktop environment. Some of the things that **KDE** brings to the user are:
386
387* A beautiful contemporary desktop
388
389* A desktop exhibiting complete network transparency
390
391* An integrated help system allowing for convenient, consistent access to help on the use of the **KDE** desktop and its applications
392
393* Consistent look and feel of all **KDE** applications
394
395* Standardized menu and toolbars, keybindings, color-schemes, etc.
396
397* Internationalization: **KDE** is available in more than 40 languages
398
399* Centralized consisted dialog driven desktop configuration
400
401* A great number of useful **KDE** applications
402
403 **KDE** comes with a web browser called **Konqueror** , which represents a solid competitor to other existing web browsers on UNIX® systems. More information on **KDE** can be found on the [KDE website](http://www.kde.org/).
404
405
406
407#### Installing KDE
408
409
410 Just as with **GNOME** or any other desktop environment, the easiest way to install **KDE** is through the pkgsrc framework or from a package:
411
412
413
414 To install the **KDE** package from the network, simply type:
415
416 # pkg_radd kde3
417
418 or if you prefer the newer **KDE 4**, type:
419
420 # pkg_radd kde4
421
422 [pkg_radd(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#pkg_radd&section1) will automatically fetch the latest version of the application.
423
424
425 To build **KDE** from source, use the pkgsrc framework:
426
427 # cd /usr/pkgsrc/meta-pkgs/kde3
428
429 # bmake install clean
430
431
432
433
434
435 After **KDE** has been installed, the X server must be told to launch this application instead of the default window manager. This is accomplished by editing the `.xinitrc` file:
436
437
438 % echo "exec startkde" > ~/.xinitrc
439
440
441 Now, whenever the X Window System is invoked with `startx`, **KDE** will be the desktop.
442
443 If a display manager such as **XDM** is being used, the configuration is slightly different. Edit the `.xsession` file instead. Instructions for **kdm** are described later in this chapter.
444
445
446
447#### More Details on KDE
448
449
450
451 Now that **KDE** is installed on the system, most things can be discovered through the help pages, or just by pointing and clicking at various menus. Windows® or Mac® users will feel quite at home.
452
453 The best reference for **KDE** is the on-line documentation. **KDE** comes with its own web browser, **Konqueror** , dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration.
454
455
456
457#### The KDE Display Manager
458
459
460
461 An administrator of a multi-user system may wish to have a graphical login screen to welcome users. [ XDM](x-xdm.html) can be used, as described earlier. However, **KDE** includes an alternative, **kdm** , which is designed to look more attractive and include more login-time options. In particular, users can easily choose (via a menu) which desktop environment ( **KDE** , **GNOME** , or something else) to run after logging on.
462
463
464
465 To enable **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
466
467
468 ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
469
470
471
472### XFce
473
474
475
476#### About XFce
477
478
479 **XFce** is a desktop environment based on the GTK+ toolkit used by **GNOME** , but is much more lightweight and meant for those who want a simple, efficient desktop which is nevertheless easy to use and configure. Visually, it looks very much like **CDE** , found on commercial UNIX systems. Some of **XFce** 's features are:
480
481* A simple, easy-to-handle desktop
482
483* Fully configurable via mouse, with drag and drop, etc
484
485* Main panel similar to **CDE** , with menus, applets and applications launchers
486
487* Integrated window manager, file manager, sound manager, **GNOME** compliance module, and other things
488
489* Themeable (since it uses GTK+)
490
491* Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
492
493
494More information on **XFce** can be found on the [XFce website](http://www.xfce.org/).
495
496
497
498#### Installing XFce
499
500
501
502 A binary package for **XFce** exists. To install, simply type:
503
504 # pkg_radd xfce4
505
506
507 Alternatively, to build from source, use the pkgsrc framework:
508
509
510
511 # cd /usr/pkgsrc/meta-pkgs/xfce4
512
513 # bmake install clean
514
515
516
517
518 Now, tell the X server to launch **XFce** the next time X is started. Simply type this:
519
520 % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
521
522
523
524 The next time X is started, **XFce** will be the desktop. As before, if a display manager like **XDM** is being used, create an `.xsession`, as described in the section on [ GNOME](x11-wm.html#X11-WM-GNOME), but with the `/usr/pkg/bin/startxfce4` command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on [ kdm](x11-wm.html#X11-WM-KDE-KDM).
525
526
527
528<!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
529
530----