(Removed redundant linefeeds for neatness.)
[ikiwiki.git] / docs / newhandbook / X / index.mdwn
1 # The X Window System 
2 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
3
4 [[!toc  levels=3]]
5
6 ## Synopsis 
7
8 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment.  In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments.  This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces. 
9
10 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
11
12 Before reading this chapter, you should know how to install additional third-party software. Read the  `dports` section of the documentation, for DragonFly 3.4 and later.
13
14 You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
15 They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
16
17 ## Understanding X 
18
19 ### What is X.Org
20
21 X.Org is the most popular free implementation of the X11 specification.  The X11 specification is an open standard, and there are other implementations, some commercial, and some free.
22
23 ### The Window Manager and the Desktop Environment
24
25 An X Server is a very low level piece of software.  It does not provide any way to move windows around or resize them. It does not provide a title bar on the top of your windows, or a dock, or any menus.
26
27 These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
28
29 Installing X.org by itself does not give you any window manager or any desktop environment. You will have to choose one and install it yourself. Until you select one, your system will not be usable.
30
31 There are dozens of window managers and desktop environments available for X. The most retro ones you might chose include `fvwm` and `twm` which have that retro 1980s workstation look and feel.  There are also window managers included inside modern desktop environments like XFCE, KDE and Gnome.  
32
33 If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
34 Every desktop environment and window manager also has a different configuration mechanism. Read your chosen environment's documentation to learn more.   Some are configured by text files alone, and some (like KDE and Gnome) have sophisticated graphical configuration utilities and "control panels".
35
36 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
37
38 ## Installing X
39
40 **X.org**  is currently available in the DragonFly dports collection.
41
42 To install:
43
44     pkg install xorg-7.7
45
46 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
47
48     pkg install xorg
49
50 ## Configuring X
51
52 You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
53
54     hald_enable ="YES"
55     dbus_enable= "YES" 
56
57 Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
58
59 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
60
61     
62
63     % startx
64
65 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually.  For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around.  Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
66
67 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
68    
69
70     # Xorg -configure
71
72 This 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.
73
74 The 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:
75
76    
77
78     # Xorg -config xorg.conf.new -retro
79
80 The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
81
82 If 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.
83
84 **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`:
85
86         # rcenable moused
87
88 Tune 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`.
89
90     
91
92 The 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).
93
94 ## The X Display Manager 
95
96  ***Contributed by Seth Kingsley.***
97
98 ### Overview 
99
100  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.
101
102  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.
103
104 ### Using XDM 
105
106  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:
107
108      
109
110     ttyv8   "/usr/pkg/bin/xdm -nodaemon"  xterm   off secure
111
112  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.
113
114 ### Configuring XDM 
115
116  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:
117
118 [[!table  data="""
119 <tablestyle="width:100%">  **File**  |  **Description**
120 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
121 `Xresources` | Default X resource values.
122 `Xservers` | List of remote and local displays to manage.
123 `Xsession` | Default session script for logins.
124 `Xsetup_`* | Script to launch applications before the login interface.
125 `xdm-config` | Global configuration for all displays running on this machine.
126 `xdm-errors` | Errors generated by the server program.
127 `xdm-pid` | The process ID of the currently running XDM. |
128
129 """]]
130
131  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).
132
133  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.
134
135 #### Xaccess 
136
137  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.
138
139 #### Xresources 
140
141  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.
142
143 #### Xservers 
144
145  This is a list of the remote displays the chooser should provide as choices.
146
147 #### Xsession 
148
149  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.
150
151 #### Xsetup_* 
152
153  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`.
154
155 #### xdm-config 
156
157  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
158
159 #### xdm-errors 
160
161  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.
162
163 ### Running a Network Display Server 
164
165  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:
166
167      
168
169     ! SECURITY: do not listen for XDMCP or Chooser requests
170
171     ! Comment out this line if you want to manage X terminals with xdm
172
173     DisplayManager.requestPort:     0
174
175  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.
176
177 ### Replacements for XDM 
178
179  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.
180
181 ----
182
183 ## Desktop Environments 
184
185  ***Contributed by Valentino Vaschetto. ***
186
187  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** .
188
189 ### GNOME 
190
191 #### About GNOME 
192
193    **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.
194
195 #### Installing GNOME 
196
197    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
198
199   To install the  **GNOME**  package from the network, simply type:
200
201     # pkg install gnome-desktop
202
203   To build  **GNOME**  from source, if you have the pkgsrc tree on your system:      
204
205     # cd /usr/pkgsrc/meta-pkgs/gnome
206
207     # bmake install clean
208
209   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
210
211   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.
212
213 **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:
214
215       
216
217     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
218
219   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
220
221 **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** :
222
223         
224
225     % echo "#!/bin/sh" > ~/.xsession
226
227     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
228
229     % chmod +x ~/.xsession
230
231   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** .
232
233 #### Anti-aliased Fonts with GNOME 
234
235   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).
236   
237   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.
238
239 ### KDE 
240
241 #### About KDE 
242
243   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
244
245 * A beautiful contemporary desktop
246
247 * A desktop exhibiting complete network transparency
248
249 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
250
251 * Consistent look and feel of all  **KDE**  applications
252
253 * Standardized menu and toolbars, keybindings, color-schemes, etc.
254
255 * Internationalization:  **KDE**  is available in more than 40 languages
256
257 * Centralized consisted dialog driven desktop configuration
258
259 * A great number of useful  **KDE**  applications
260
261   **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/).
262
263 #### Installing KDE 
264
265  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
266
267  To install the  **KDE**  4.10 package from the network, simply type:
268
269    # pkg install kde-4.10
270
271  To build  **KDE**  from source, using the pkgsrc framework:
272
273     # cd /usr/pkgsrc/meta-pkgs/kde3
274
275     # bmake install clean
276
277  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:
278
279     % echo "exec startkde" > ~/.xinitrc
280
281  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
282
283  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.
284
285 #### More Details on KDE 
286
287  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.
288
289  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.
290
291 #### The KDE Display Manager 
292
293  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.
294
295  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
296   
297
298     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
299
300     
301 ### XFce 
302
303 #### About XFce 
304
305   **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:
306
307 * A simple, easy-to-handle desktop
308
309 * Fully configurable via mouse, with drag and drop, etc
310
311 * Main panel similar to  **CDE** , with menus, applets and applications launchers
312
313 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
314
315 * Themeable (since it uses GTK+)
316
317 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
318
319 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
320
321 #### Installing XFce 
322
323  A binary package for  **XFce**  exists. To install, simply type:
324
325     # pkg install xfce
326
327 This should install the main xfce4 desktop package, and most of the required components.
328
329  Alternatively, to build from source, use the pkgsrc framework:
330
331    
332
333     # cd /usr/pkgsrc/meta-pkgs/xfce4
334
335     # bmake install clean
336
337  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
338
339     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
340
341  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).
342
343 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
344
345 ----
346 # The X Window System 
347 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
348
349 [[!toc  levels=3]]
350
351 ## Synopsis 
352
353 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment.  In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments.  This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces. 
354
355 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
356
357 Before reading this chapter, you should know how to install additional third-party software. Read the  `dports` section of the documentation, for DragonFly 3.4 and later.
358
359 You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
360 They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
361
362 ## Understanding X 
363
364 ### What is X.Org
365
366 X.Org is the most popular free implementation of the X11 specification.  The X11 specification is an open standard, and there are other implementations, some commercial, and some free.
367
368 ### The Window Manager and the Desktop Environment
369
370 An X Server is a very low level piece of software.  It does not provide any way to move windows around or resize them. It does not provide a title bar on the top of your windows, or a dock, or any menus.
371
372 These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
373
374 Installing X.org by itself does not give you any window manager or any desktop environment. You will have to choose one and install it yourself. Until you select one, your system will not be usable.
375
376 There are dozens of window managers and desktop environments available for X. The most retro ones you might chose include `fvwm` and `twm` which have that retro 1980s workstation look and feel.  There are also window managers included inside modern desktop environments like XFCE, KDE and Gnome.  
377
378 If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
379 Every desktop environment and window manager also has a different configuration mechanism. Read your chosen environment's documentation to learn more.   Some are configured by text files alone, and some (like KDE and Gnome) have sophisticated graphical configuration utilities and "control panels".
380
381 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
382
383 ## Installing X
384
385 **X.org**  is currently available in the DragonFly dports collection.
386
387 To install:
388
389     pkg install xorg-7.7
390
391 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
392
393     pkg install xorg
394
395 ## Configuring X
396
397 You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
398
399     hald_enable ="YES"
400     dbus_enable= "YES" 
401
402 Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
403
404 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
405
406     
407
408     % startx
409
410 If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually.  For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around.  Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
411
412 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
413    
414
415     # Xorg -configure
416
417 This 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&amp;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.
418
419 The 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:
420
421    
422
423     # Xorg -config xorg.conf.new -retro
424
425 The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
426
427 If 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.
428
429 **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`:
430
431         # rcenable moused
432
433 Tune 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`.
434
435     
436
437 The 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).
438
439 ## The X Display Manager 
440
441  ***Contributed by Seth Kingsley.***
442
443 ### Overview 
444
445  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.
446
447  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.
448
449 ### Using XDM 
450
451  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:
452
453      
454
455     ttyv8   "/usr/pkg/bin/xdm -nodaemon"  xterm   off secure
456
457  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.
458
459 ### Configuring XDM 
460
461  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:
462
463 [[!table  data="""
464 <tablestyle="width:100%">  **File**  |  **Description**
465 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
466 `Xresources` | Default X resource values.
467 `Xservers` | List of remote and local displays to manage.
468 `Xsession` | Default session script for logins.
469 `Xsetup_`* | Script to launch applications before the login interface.
470 `xdm-config` | Global configuration for all displays running on this machine.
471 `xdm-errors` | Errors generated by the server program.
472 `xdm-pid` | The process ID of the currently running XDM. |
473
474 """]]
475
476  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).
477
478  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.
479
480 #### Xaccess 
481
482  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.
483
484 #### Xresources 
485
486  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.
487
488 #### Xservers 
489
490  This is a list of the remote displays the chooser should provide as choices.
491
492 #### Xsession 
493
494  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.
495
496 #### Xsetup_* 
497
498  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`.
499
500 #### xdm-config 
501
502  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
503
504 #### xdm-errors 
505
506  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.
507
508 ### Running a Network Display Server 
509
510  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:
511
512      
513
514     ! SECURITY: do not listen for XDMCP or Chooser requests
515
516     ! Comment out this line if you want to manage X terminals with xdm
517
518     DisplayManager.requestPort:     0
519
520  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.
521
522 ### Replacements for XDM 
523
524  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.
525
526 ----
527
528 ## Desktop Environments 
529
530  ***Contributed by Valentino Vaschetto. ***
531
532  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** .
533
534 ### GNOME 
535
536 #### About GNOME 
537
538    **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.
539
540 #### Installing GNOME 
541
542    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
543
544   To install the  **GNOME**  package from the network, simply type:
545
546     # pkg install gnome-desktop
547
548   To build  **GNOME**  from source, if you have the pkgsrc tree on your system:      
549
550     # cd /usr/pkgsrc/meta-pkgs/gnome
551
552     # bmake install clean
553
554   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
555
556   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.
557
558 **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:
559
560       
561
562     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
563
564   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
565
566 **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** :
567
568         
569
570     % echo "#!/bin/sh" > ~/.xsession
571
572     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
573
574     % chmod +x ~/.xsession
575
576   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** .
577
578 #### Anti-aliased Fonts with GNOME 
579
580   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).
581   
582   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.
583
584 ### KDE 
585
586 #### About KDE 
587
588   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
589
590 * A beautiful contemporary desktop
591
592 * A desktop exhibiting complete network transparency
593
594 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
595
596 * Consistent look and feel of all  **KDE**  applications
597
598 * Standardized menu and toolbars, keybindings, color-schemes, etc.
599
600 * Internationalization:  **KDE**  is available in more than 40 languages
601
602 * Centralized consisted dialog driven desktop configuration
603
604 * A great number of useful  **KDE**  applications
605
606   **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/).
607
608 #### Installing KDE 
609
610  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
611
612  To install the  **KDE**  4.10 package from the network, simply type:
613
614    # pkg install kde-4.10
615
616  To build  **KDE**  from source, using the pkgsrc framework:
617
618     # cd /usr/pkgsrc/meta-pkgs/kde3
619
620     # bmake install clean
621
622  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:
623
624     % echo "exec startkde" > ~/.xinitrc
625
626  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
627
628  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.
629
630 #### More Details on KDE 
631
632  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.
633
634  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.
635
636 #### The KDE Display Manager 
637
638  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.
639
640  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
641   
642     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
643
644     
645 ### XFce 
646
647 #### About XFce 
648
649   **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:
650
651 * A simple, easy-to-handle desktop
652
653 * Fully configurable via mouse, with drag and drop, etc
654
655 * Main panel similar to  **CDE** , with menus, applets and applications launchers
656
657 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
658
659 * Themeable (since it uses GTK+)
660
661 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
662
663 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
664
665 #### Installing XFce 
666
667  A binary package for  **XFce**  exists. To install, simply type:
668
669     # pkg install xfce
670
671 This should install the main xfce4 desktop package, and most of the required components.
672
673  Alternatively, to build from source, use the pkgsrc framework:
674
675     # cd /usr/pkgsrc/meta-pkgs/xfce4
676
677     # bmake install clean
678
679  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
680
681     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
682
683  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).
684
685 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
686
687 ----