(Removed duplicate section. Restore if it isn't in fact duplicate please.)
[ikiwiki.git] / docs / newhandbook / X / index.mdwn
a86df2f3 1# The X Window System
4d10e196 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***
a86df2f3 3
ca543863 4[[!toc levels=3]]
a86df2f3 6## Synopsis
3a394b59 8This 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.
a86df2f3 9
35fb3679 10For 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.
a86df2f3 11
3a394b59 12Before 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.
a86df2f3 13
14You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
15They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
a86df2f3 16
a86df2f3 17## Understanding X
19### What is X.Org
21X.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.
bed9fc81 23### The Window Manager and the Desktop Environment
a86df2f3 24
bed9fc81 25An 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.
a86df2f3 26
bed9fc81 27These things are the job, in the oldest style of X environment, of your window manager, or in more recent times, of a Desktop Environment.
a86df2f3 28
bed9fc81 29Installing 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.
a86df2f3 30
bed9fc81 31There 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.
a86df2f3 32
33If you are brand new and don't know what to do, select the XFCE4 desktop and follow those instructions.
34Every 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".
a86df2f3 35
bed9fc81 36Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
a86df2f3 37
a86df2f3 38## Installing X
4d10e196 40**X.org** is currently available in the DragonFly dports collection.
a86df2f3 41
5fa36c0a 42To install:
a86df2f3 43
f5e2e40e 44 pkg install xorg-7.7
a86df2f3 45
4d10e196 46By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
a86df2f3 47
f5e2e40e 48 pkg install xorg
a86df2f3 49
a86df2f3 50## Configuring X
8da48ac3 52You 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:
a86df2f3 53
54 hald_enable ="YES"
55 dbus_enable= "YES"
49405676 56
8da48ac3 57Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
a86df2f3 58
32c109d2 59As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
a86df2f3 60
32c109d2 61
a86df2f3 62
32c109d2 63 % startx
a86df2f3 64
65If 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.
4a6774f7 67Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
32c109d2 68
a86df2f3 69
32c109d2 70 # Xorg -configure
a86df2f3 71
32c109d2 72This 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 73
32c109d2 74The 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 75
32c109d2 76
a86df2f3 77
e9cd5e79 78 # Xorg -config xorg.conf.new -retro
a86df2f3 79
e9cd5e79 80The -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.
a86df2f3 81
32c109d2 82If 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 83
32c109d2 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`:
a86df2f3 85
32c109d2 86 # rcenable moused
a86df2f3 87
8ff68d2e 88Tune 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 89
a86df2f3 92The 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).
0edfba91 94## The X Display Manager
a86df2f3 95
0edfba91 96 ***Contributed by Seth Kingsley.***
a86df2f3 97
0edfba91 98### Overview
a86df2f3 99
0edfba91 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.
a86df2f3 101
0edfba91 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.
a86df2f3 103
0edfba91 104### Using XDM
a86df2f3 105
0edfba91 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](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the **XDM** daemon on a virtual terminal:
a86df2f3 107
0edfba91 108
a86df2f3 109
0edfba91 110 ttyv8 "/usr/pkg/bin/xdm -nodaemon" xterm off secure
a86df2f3 111
0edfba91 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](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.
a86df2f3 113
0edfba91 114### Configuring XDM
a86df2f3 115
0edfba91 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:
a86df2f3 117
0edfba91 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. |
a86df2f3 128
0edfba91 129"""]]
a86df2f3 130
0edfba91 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).
a86df2f3 132
0edfba91 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.
a86df2f3 134
0edfba91 135#### Xaccess
a86df2f3 136
0edfba91 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.
a86df2f3 138
0edfba91 139#### Xresources
a86df2f3 140
0edfba91 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.
a86df2f3 142
0edfba91 143#### Xservers
a86df2f3 144
0edfba91 145 This is a list of the remote displays the chooser should provide as choices.
147#### Xsession
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.
151#### Xsetup_*
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`.
155#### xdm-config
157 This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
159#### xdm-errors
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.
163### Running a Network Display Server
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:
a86df2f3 166
0edfba91 169 ! SECURITY: do not listen for XDMCP or Chooser requests
a86df2f3 170
0edfba91 171 ! Comment out this line if you want to manage X terminals with xdm
a86df2f3 172
0edfba91 173 DisplayManager.requestPort: 0
a86df2f3 174
0edfba91 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.
a86df2f3 176
0edfba91 177### Replacements for XDM
a86df2f3 178
0edfba91 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.
a86df2f3 180
0edfba91 181----
a86df2f3 182
0edfba91 183## Desktop Environments
a86df2f3 184
0edfba91 185 ***Contributed by Valentino Vaschetto. ***
a86df2f3 186
0edfba91 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** .
a86df2f3 188
0edfba91 189### GNOME
a86df2f3 190
0edfba91 191#### About GNOME
a86df2f3 192
0edfba91 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.
a86df2f3 194
0edfba91 195#### Installing GNOME
a86df2f3 196
0edfba91 197 **GNOME** can be easily installed from a package or from the pkgsrc framework:
a86df2f3 198
0edfba91 199 To install the **GNOME** package from the network, simply type:
a86df2f3 200
0edfba91 201 # pkg install gnome-desktop
a86df2f3 202
0edfba91 203 To build **GNOME** from source, if you have the pkgsrc tree on your system:
a86df2f3 204
0edfba91 205 # cd /usr/pkgsrc/meta-pkgs/gnome
a86df2f3 206
0edfba91 207 # bmake install clean
a86df2f3 208
0edfba91 209 Once **GNOME** is installed, the X server must be told to start **GNOME** instead of a default window manager.
a86df2f3 210
0edfba91 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.
a86df2f3 212
0edfba91 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:
a86df2f3 214
0edfba91 215
a86df2f3 216
0edfba91 217 % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
a86df2f3 218
0edfba91 219 Next, type `startx`, and the **GNOME** desktop environment will be started.
a86df2f3 220
0edfba91 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** :
a86df2f3 222
0edfba91 223
a86df2f3 224
0edfba91 225 % echo "#!/bin/sh" > ~/.xsession
a86df2f3 226
0edfba91 227 % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
a86df2f3 228
0edfba91 229 % chmod +x ~/.xsession
a86df2f3 230
0edfba91 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** .
a86df2f3 232
0edfba91 233#### Anti-aliased Fonts with GNOME
a86df2f3 234
0edfba91 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).
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.
a86df2f3 238
0edfba91 239### KDE
a86df2f3 240
0edfba91 241#### About KDE
a86df2f3 242
0edfba91 243 **KDE** is an easy to use contemporary desktop environment. Some of the things that **KDE** brings to the user are:
a86df2f3 244
0edfba91 245* A beautiful contemporary desktop
a86df2f3 246
0edfba91 247* A desktop exhibiting complete network transparency
a86df2f3 248
0edfba91 249* An integrated help system allowing for convenient, consistent access to help on the use of the **KDE** desktop and its applications
a86df2f3 250
0edfba91 251* Consistent look and feel of all **KDE** applications
a86df2f3 252
0edfba91 253* Standardized menu and toolbars, keybindings, color-schemes, etc.
a86df2f3 254
0edfba91 255* Internationalization: **KDE** is available in more than 40 languages
a86df2f3 256
0edfba91 257* Centralized consisted dialog driven desktop configuration
a86df2f3 258
0edfba91 259* A great number of useful **KDE** applications
a86df2f3 260
0edfba91 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/).
a86df2f3 262
0edfba91 263#### Installing KDE
a86df2f3 264
0edfba91 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:
a86df2f3 266
0edfba91 267 To install the **KDE** 4.10 package from the network, simply type:
a86df2f3 268
0edfba91 269 # pkg install kde-4.10
a86df2f3 270
0edfba91 271 To build **KDE** from source, using the pkgsrc framework:
a86df2f3 272
0edfba91 273 # cd /usr/pkgsrc/meta-pkgs/kde3
a86df2f3 274
0edfba91 275 # bmake install clean
a86df2f3 276
0edfba91 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:
a86df2f3 278
0edfba91 279 % echo "exec startkde" > ~/.xinitrc
a86df2f3 280
0edfba91 281 Now, whenever the X Window System is invoked with `startx`, **KDE** will be the desktop.
a86df2f3 282
0edfba91 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.
a86df2f3 284
0edfba91 285#### More Details on KDE
a86df2f3 286
0edfba91 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.
a86df2f3 288
0edfba91 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.
a86df2f3 290
0edfba91 291#### The KDE Display Manager
a86df2f3 292
0edfba91 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.
a86df2f3 294
0edfba91 295 To enable **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
a86df2f3 297
0edfba91 298 ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
a86df2f3 299
0edfba91 300
301### XFce
a86df2f3 302
0edfba91 303#### About XFce
a86df2f3 304
0edfba91 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:
a86df2f3 306
0edfba91 307* A simple, easy-to-handle desktop
a86df2f3 308
0edfba91 309* Fully configurable via mouse, with drag and drop, etc
a86df2f3 310
0edfba91 311* Main panel similar to **CDE** , with menus, applets and applications launchers
a86df2f3 312
0edfba91 313* Integrated window manager, file manager, sound manager, **GNOME** compliance module, and other things
a86df2f3 314
0edfba91 315* Themeable (since it uses GTK+)
a86df2f3 316
0edfba91 317* Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
a86df2f3 318
0edfba91 319More information on **XFce** can be found on the [XFce website](http://www.xfce.org/).
a86df2f3 320
0edfba91 321#### Installing XFce
a86df2f3 322
0edfba91 323 A binary package for **XFce** exists. To install, simply type:
a86df2f3 324
0edfba91 325 # pkg install xfce
a86df2f3 326
0edfba91 327This should install the main xfce4 desktop package, and most of the required components.
a86df2f3 328
0edfba91 329 Alternatively, to build from source, use the pkgsrc framework:
a86df2f3 330
0edfba91 331
a86df2f3 332
0edfba91 333 # cd /usr/pkgsrc/meta-pkgs/xfce4
a86df2f3 334
0edfba91 335 # bmake install clean
a86df2f3 336
0edfba91 337 Now, tell the X server to launch **XFce** the next time X is started. Simply type this:
a86df2f3 338
0edfba91 339 % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
a86df2f3 340
0edfba91 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).
a86df2f3 342
0edfba91 343<!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
a86df2f3 344