An installation of &os; using bsdinstall does not automatically install a graphical user interface. This chapter describes how to install and configure &xorg;, which provides the open source X Window System used to provide a graphical environment. It then describes how to find and install a desktop environment or window manager. Users who prefer an installation method that automatically configures the &xorg; and offers a choice of window managers during installation should refer to the website. For more information on the video hardware that &xorg; supports, refer to the x.org website. After reading this chapter, you will know: The various components of the X Window System, and how they interoperate. How to install and configure &xorg;. How to install and configure several window managers and desktop environments. How to use &truetype; fonts in &xorg;. How to set up your system for graphical logins (XDM). Before reading this chapter, you should: Know how to install additional third-party software as described in . While it is not necessary to understand all of the details of the various components in the X Window System and how they interact, some basic knowledge of these components can be useful. X server X was designed from the beginning to be network-centric, and adopts a client-server model. In this model, the X server runs on the computer that has the keyboard, monitor, and mouse attached. The server's responsibility includes tasks such as managing the display, handling input from the keyboard and mouse, and handling input or output from other devices such as a tablet or a video projector. This confuses some people, because the X terminology is exactly backward to what they expect. They expect the X server to be the big powerful machine down the hall, and the X client to be the machine on their desk. X client Each X application, such as XTerm or Firefox, is a client. A client sends messages to the server such as Please draw a window at these coordinates, and the server sends back messages such as The user just clicked on the OK button. In a home or small office environment, the X server and the X clients commonly run on the same computer. It is also possible to run the X server on a less powerful computer and to run the X applications on a more powerful system. In this scenario, the communication between the X client and server takes place over the network. window manager X does not dictate what windows should look like on-screen, how to move them around with the mouse, which keystrokes should be used to move between windows, what the title bars on each window should look like, whether or not they have close buttons on them, and so on. Instead, X delegates this responsibility to a separate window manager application. There are dozens of window managers available. Each window manager provides a different look and feel: some support virtual desktops, some allow customized keystrokes to manage the desktop, some have a Start button, and some are themeable, allowing a complete change of the desktop's look-and-feel. Window managers are available in the x11-wm category of the Ports Collection. Each window manager uses a different configuration mechanism. Some expect configuration file written by hand while others provide graphical tools for most configuration tasks. desktop environment KDE and GNOME are considered to be desktop environments as they include an entire suite of applications for performing common desktop tasks. These may include office suites, web browsers, and games. focus policy The window manager is responsible for the mouse focus policy. This policy provides some means for choosing which window is actively receiving keystrokes and it should also visibly indicate which window is currently active. One focus policy is called click-to-focus. In this model, a window becomes active upon receiving a mouse click. In the focus-follows-mouse policy, the window that is under the mouse pointer has focus and the focus is changed by pointing at another window. If the mouse is over the root window, then this window is focused. In the sloppy-focus model, if the mouse is moved over the root window, the most recently used window still has the focus. With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window. In the click-to-focus policy, the active window is selected by mouse click. The window may then be raised and appear in front of all other windows. All keystrokes will now be directed to this window, even if the cursor is moved to another window. Different window managers support different focus models. All of them support click-to-focus, and the majority of them also support other policies. Consult the documentation for the window manager to determine which focus models are available. widgets Widget is a term for all of the items in the user interface that can be clicked or manipulated in some way. This includes buttons, check boxes, radio buttons, icons, and lists. A widget toolkit is a set of widgets used to create graphical applications. There are several popular widget toolkits, including Qt, used by KDE, and GTK+, used by GNOME. As a result, applications will have a different look and feel, depending upon which widget toolkit was used to create the application. On &os;, &xorg; can be installed as a package or port. The binary package can be installed quickly but with fewer options for customization: &prompt.root; pkg install xorg To build and install from the Ports Collection: &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean Either of these installations results in the complete &xorg; system being installed. Binary packages are the best option for most users. A smaller version of the X system suitable for experienced users is available in x11/xorg-minimal. Most of the documents, libraries, and applications will not be installed. Some applications require these additional components to function. Warren Block Originally contributed by &xorg; &xorg; &xorg; supports most common video cards, keyboards, and pointing devices. Video cards, monitors, and input devices are automatically detected and do not require any manual configuration. Do not create xorg.conf or run a -configure step unless automatic configuration fails. If &xorg; has been used on this computer before, move or remove any existing configuration files: &prompt.root; mv /etc/X11/xorg.conf ~/xorg.conf.etc &prompt.root; mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc Add the user who will run &xorg; to the video or wheel group to enable 3D acceleration when available. To add user jru to whichever group is available: &prompt.root; pw groupmod video -m jru || pw groupmod wheel -m jru The TWM window manager is included by default. It is started when &xorg; starts: &prompt.user; startx On some older versions of &os;, the system console must be set to &man.vt.4; before switching back to the text console will work properly. See . Access to /dev/dri is needed to allow 3D acceleration on video cards. It is usually simplest to add the user who will be running X to either the video or wheel group. Here, &man.pw.8; is used to add user slurms to the video group, or to the wheel group if there is no video group: &prompt.root; pw groupmod video -m slurms || pw groupmod wheel -m slurms When the computer switches from displaying the console to a higher screen resolution for X, it must set the video output mode. Recent versions of &xorg; use a system inside the kernel to do these mode changes more efficiently. Older versions of &os; use &man.sc.4;, which is not aware of the KMS system. The end result is that after closing X, the system console is blank, even though it is still working. The newer &man.vt.4; console avoids this problem. Add this line to /boot/loader.conf to enable &man.vt.4;: kern.vty=vt Manual configuration is usually not necessary. Please do not manually create configuration files unless autoconfiguration does not work. &xorg; looks in several directories for configuration files. /usr/local/etc/X11/ is the recommended directory for these files on &os;. Using this directory helps keep application files separate from operating system files. Storing configuration files in the legacy /etc/X11/ still works. However, this mixes application files with the base &os; files and is not recommended. It is easier to use multiple files that each configure a specific setting than the traditional single xorg.conf. These files are stored in the xorg.conf.d/ subdirectory of the main configuration file directory. The full path is typically /usr/local/etc/X11/xorg.conf.d/. Examples of these files are shown later in this section. The traditional single xorg.conf still works, but is neither as clear nor as flexible as multiple files in the xorg.conf.d/ subdirectory. &intel; 3D acceleration is supported on most &intel; graphics up to Ivy Bridge (HD Graphics 2500, 4000, and P4000), including Iron Lake (HD Graphics) and Sandy Bridge (HD Graphics 2000). Driver name: intel For reference, see . &amd; Radeon 2D and 3D acceleration is supported on Radeon cards up to and including the HD6000 series. Driver name: radeon For reference, see . NVIDIA Several NVIDIA drivers are available in the x11 category of the Ports Collection. Install the driver that matches the video card. For reference, see . Hybrid Combination Graphics Some notebook computers add additional graphics processing units to those built into the chipset or processor. Optimus combines &intel; and NVIDIA hardware. Switchable Graphics or Hybrid Graphics are a combination of an &intel; or &amd; processor and an &amd; Radeon GPU. Implementations of these hybrid graphics systems vary, and &xorg; on &os; is not able to drive all versions of them. Some computers provide a BIOS option to disable one of the graphics adapters or select a discrete mode which can be used with one of the standard video card drivers. For example, it is sometimes possible to disable the NVIDIA GPU in an Optimus system. The &intel; video can then be used with an &intel; driver. BIOS settings depend on the model of computer. In some situations, both GPUs can be left enabled, but creating a configuration file that only uses the main GPU in the Device section is enough to make such a system functional. Other Video Cards Drivers for some less-common video cards can be found in the x11-drivers directory of the Ports Collection. Cards that are not supported by a specific driver might still be usable with the x11-drivers/xf86-video-vesa driver. This driver is installed by x11/xorg. It can also be installed manually as x11-drivers/xf86-video-vesa. &xorg; attempts to use this driver when a specific driver is not found for the video card. x11-drivers/xf86-video-scfb is a similar nonspecialized video driver that works on many UEFI and &arm; computers. Setting the Video Driver in a File To set the &intel; driver in a configuration file: /usr/local/etc/X11/xorg.conf.d/driver-intel.conf Section "Device" Identifier "Card0" Driver "intel" # BusID "PCI:1:0:0" EndSection If more than one video card is present, the BusID identifier can be uncommented and set to select the desired card. A list of video card bus IDs can be displayed with pciconf -lv | grep -B3 display. To set the Radeon driver in a configuration file: /usr/local/etc/X11/xorg.conf.d/driver-radeon.conf Section "Device" Identifier "Card0" Driver "radeon" EndSection To set the VESA driver in a configuration file: /usr/local/etc/X11/xorg.conf.d/driver-vesa.conf Section "Device" Identifier "Card0" Driver "vesa" EndSection To set the scfb driver for use with a UEFI or &arm; computer: /usr/local/etc/X11/xorg.conf.d/driver-scfb.conf Section "Device" Identifier "Card0" Driver "scfb" EndSection Almost all monitors support the Extended Display Identification Data standard (EDID). &xorg; uses EDID to communicate with the monitor and detect the supported resolutions and refresh rates. Then it selects the most appropriate combination of settings to use with that monitor. Other resolutions supported by the monitor can be chosen by setting the desired resolution in configuration files, or after the X server has been started with &man.xrandr.1;. Using &man.xrandr.1; Run &man.xrandr.1; without any parameters to see a list of video outputs and detected monitor modes: &prompt.user; xrandr Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192 DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm 1920x1200 59.95*+ 1600x1200 60.00 1280x1024 85.02 75.02 60.02 1280x960 60.00 1152x864 75.00 1024x768 85.00 75.08 70.07 60.00 832x624 74.55 800x600 75.00 60.32 640x480 75.00 60.00 720x400 70.08 DisplayPort-0 disconnected (normal left inverted right x axis y axis) HDMI-0 disconnected (normal left inverted right x axis y axis) This shows that the DVI-0 output is being used to display a screen resolution of 1920x1200 pixels at a refresh rate of about 60 Hz. Monitors are not attached to the DisplayPort-0 and HDMI-0 connectors. Any of the other display modes can be selected with &man.xrandr.1;. For example, to switch to 1280x1024 at 60 Hz: &prompt.user; xrandr --mode 1280x1024 --rate 60 A common task is using the external video output on a notebook computer for a video projector. The type and quantity of output connectors varies between devices, and the name given to each output varies from driver to driver. What one driver calls HDMI-1, another might call HDMI1. So the first step is to run &man.xrandr.1; to list all the available outputs: &prompt.user; xrandr Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192 LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm 1366x768 60.04*+ 1024x768 60.00 800x600 60.32 56.25 640x480 59.94 VGA1 connected (normal left inverted right x axis y axis) 1280x1024 60.02 + 75.02 1280x960 60.00 1152x864 75.00 1024x768 75.08 70.07 60.00 832x624 74.55 800x600 72.19 75.00 60.32 56.25 640x480 75.00 72.81 66.67 60.00 720x400 70.08 HDMI1 disconnected (normal left inverted right x axis y axis) DP1 disconnected (normal left inverted right x axis y axis) Four outputs were found: the built-in panel LVDS1, and external VGA1, HDMI1, and DP1 connectors. The projector has been connected to the VGA1 output. &man.xrandr.1; is now used to set that output to the native resolution of the projector and add the additional space to the right side of the desktop: &prompt.user; xrandr --output VGA1 --auto --right-of LVDS1 --auto chooses the resolution and refresh rate detected by EDID. If the resolution is not correctly detected, a fixed value can be given with --mode instead of the --auto statement. For example, most projectors can be used with a 1024x768 resolution, which is set with --mode 1024x768. &man.xrandr.1; is often run from .xinitrc to set the appropriate mode when X starts. Setting Monitor Resolution in a File To set a screen resolution of 1024x768 in a configuration file: /usr/local/etc/X11/xorg.conf.d/screen-resolution.conf Section "Screen" Identifier "Screen0" Device "Card0" SubSection "Display" Modes "1024x768" EndSubSection EndSection The few monitors that do not have EDID can be configured by setting HorizSync and VertRefresh to the range of frequencies supported by the monitor. /usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf Section "Monitor" Identifier "Monitor0" HorizSync 30-83 # kHz VertRefresh 50-76 # Hz EndSection Keyboard Layout The standardized location of keys on a keyboard is called a layout. Layouts and other adjustable parameters are listed in &man.xkeyboard-config.7;. A United States layout is the default. To select an alternate layout, set the XkbLayout and XkbVariant options in an InputClass. This will be applied to all input devices that match the class. This example selects a French keyboard layout with the oss variant. /usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbLayout" "fr" Option "XkbVariant" "oss" EndSection Set United States, Spanish, and Ukrainian keyboard layouts. Cycle through these layouts by pressing Alt Shift . x11/xxkb or x11/sbxkb can be used for improved layout switching control and current layout indicators. /usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf Section "InputClass" Identifier "All Keyboards" MatchIsKeyboard "yes" Option "XkbLayout" "us, es, ua" EndSection Closing &xorg; From the Keyboard X can be closed with a combination of keys. By default, that key combination is not set because it conflicts with keyboard commands for some applications. Enabling this option requires changes to the keyboard InputDevice section: /usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbOptions" "terminate:ctrl_alt_bksp" EndSection Many mouse parameters can be adjusted with configuration options. See &man.mousedrv.4x; for a full list. Mouse Buttons The number of buttons on a mouse can be set in the mouse InputDevice section of xorg.conf. To set the number of buttons to 7: /usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf Section "InputDevice" Identifier "Mouse0" Option "Buttons" "7" EndSection In some cases, &xorg; autoconfiguration does not work with particular hardware, or a different configuration is desired. For these cases, a custom configuration file can be created. Do not create manual configuration files unless required. Unnecessary manual configuration can prevent proper operation. A configuration file can be generated by &xorg; based on the detected hardware. This file is often a useful starting point for custom configurations. Generating an xorg.conf: &prompt.root; Xorg -configure The configuration file is saved to /root/xorg.conf.new. Make any changes desired, then test that file with: &prompt.root; Xorg -config /root/xorg.conf.new After the new configuration has been adjusted and tested, it can be split into smaller files in the normal location, /usr/local/etc/X11/xorg.conf.d/. The default fonts that ship with &xorg; are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible. However, there are several free, high quality Type1 (&postscript;) fonts available which can be readily used with &xorg;. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefonts collection (x11-fonts/freefonts) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, &xorg; can be configured to use &truetype; fonts with a minimum of effort. For more details on this, see the &man.X.7; manual page or . To install the above Type1 font collections from binary packages, run the following commands: &prompt.root; pkg install urwfonts Alternatively, to build from the Ports Collection, run the following commands: &prompt.root; cd /usr/ports/x11-fonts/urwfonts &prompt.root; make install clean And likewise with the freefont or other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file (/etc/X11/xorg.conf), which reads: FontPath "/usr/local/share/fonts/urwfonts/" Alternatively, at the command line in the X session run: &prompt.user; xset fp+ /usr/local/share/fonts/urwfonts &prompt.user; xset fp rehash This will work but will be lost when the X session is closed, unless it is added to the startup file (~/.xinitrc for a normal startx session, or ~/.xsession when logging in through a graphical login manager like XDM). A third way is to use the new /usr/local/etc/fonts/local.conf as demonstrated in . TrueType Fonts fonts TrueType &xorg; has built in support for rendering &truetype; fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the "Module" section of /etc/X11/xorg.conf. Load "freetype" Now make a directory for the &truetype; fonts (for example, /usr/local/share/fonts/TrueType) and copy all of the &truetype; fonts into this directory. Keep in mind that &truetype; fonts cannot be directly taken from an &apple; &mac;; they must be in &unix;/&ms-dos;/&windows; format for use by &xorg;. Once the files have been copied into this directory, use mkfontdir to create a fonts.dir, so that the X font renderer knows that these new files have been installed. mkfontdir can be installed as a package: &prompt.root; pkg install mkfontdir Then create an index of X font files in a directory: &prompt.root; cd /usr/local/share/fonts/TrueType &prompt.root; mkfontdir Now add the &truetype; directory to the font path. This is just the same as described in : &prompt.user; xset fp+ /usr/local/share/fonts/TrueType &prompt.user; xset fp rehash or add a FontPath line to xorg.conf. Now Gimp, Apache OpenOffice, and all of the other X applications should now recognize the installed &truetype; fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within &staroffice;) will look much better now. anti-aliased fonts fonts anti-aliased All fonts in &xorg; that are found in /usr/local/share/fonts/ and ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox. To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file /usr/local/etc/fonts/local.conf. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see &man.fonts-conf.5;. XML This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the <fontconfig> tag: <?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> As previously stated, all fonts in /usr/local/share/fonts/ as well as ~/.fonts/ are already made available to Xft-aware applications. To add another directory outside of these two directory trees, add a line like this to /usr/local/etc/fonts/local.conf: <dir>/path/to/my/fonts</dir> After adding new fonts, and especially new font directories, rebuild the font caches: &prompt.root; fc-cache -f Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes staircases from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines: <match target="font"> <test name="size" compare="less"> <double>14</double> </test> <edit name="antialias" mode="assign"> <bool>false</bool> </edit> </match> <match target="font"> <test name="pixelsize" compare="less" qual="any"> <double>14</double> </test> <edit mode="assign" name="antialias"> <bool>false</bool> </edit> </match> fonts spacing Spacing for some monospaced fonts might also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix is to force the spacing for such fonts to be 100. Add these lines: <match target="pattern" name="family"> <test qual="any" name="family"> <string>fixed</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> <match target="pattern" name="family"> <test qual="any" name="family"> <string>console</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> (this aliases the other common names for fixed fonts as "mono"), and then add: <match target="pattern" name="family"> <test qual="any" name="family"> <string>mono</string> </test> <edit name="spacing" mode="assign"> <int>100</int> </edit> </match> Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications to crash. To avoid this, consider adding the following to local.conf: <match target="pattern" name="family"> <test qual="any" name="family"> <string>Helvetica</string> </test> <edit name="family" mode="assign"> <string>sans-serif</string> </edit> </match> After editing local.conf, make certain to end the file with the </fontconfig> tag. Not doing this will cause changes to be ignored. Users can add personalized settings by creating their own ~/.config/fontconfig/fonts.conf. This file uses the same XML format described above. LCD screen Fonts LCD screen One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in local.conf: <match target="font"> <test qual="all" name="rgba"> <const>unknown</const> </test> <edit name="rgba" mode="assign"> <const>rgb</const> </edit> </match> Depending on the sort of display, rgb may need to be changed to bgr, vrgb or vbgr: experiment and see which works best. Seth Kingsley Contributed by X Display Manager &xorg; provides an X Display Manager, XDM, which can be used for login session management. XDM provides a graphical interface for choosing which display server to connect to and for entering authorization information such as a login and password combination. This section demonstrates how to configure the X Display Manager on &os;. Some desktop environments provide their own graphical login manager. Refer to for instructions on how to configure the GNOME Display Manager and for instructions on how to configure the KDE Display Manager. To install XDM, use the x11/xdm package or port. Once installed, XDM can be configured to run when the machine boots up by editing this entry in /etc/ttys: ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure Change the off to on and save the edit. The ttyv8 in this entry indicates that XDM will run on the ninth virtual terminal. The XDM configuration directory is located in /usr/local/lib/X11/xdm. This directory contains several files used to change the behavior and appearance of XDM, as well as a few scripts and programs used to set up the desktop when XDM is running. summarizes the function of each of these files. The exact syntax and usage of these files is described in &man.xdm.1;. File Description Xaccess The protocol for connecting to XDM is called the X Display Manager Connection Protocol (XDMCP) This file is a client authorization ruleset for controlling XDMCP connections from remote machines. By default, this file does not allow any remote clients to connect. Xresources This file controls the look and feel of the XDM display chooser and login screens. 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. The format of this file is identical to the app-defaults file described in the &xorg; documentation. Xservers The list of local and remote displays the chooser should provide as login choices. Xsession Default session script for logins which is run by XDM after a user has logged in. Normally each user will have a customized session script in ~/.xsession that overrides this script Xsetup_* Script to automatically launch applications before displaying the chooser or login interfaces. There is a script for each display being used, named Xsetup_*, where * is the local display number. Typically these scripts run one or two programs in the background such as xconsole. xdm-config Global configuration for all displays running on this machine. xdm-errors Contains errors generated by the server program. If a display that XDM is trying to start hangs, look at this file for error messages. These messages are also written to the user's ~/.xsession-errors on a per-session basis. xdm-pid The running process ID of XDM. By default, only users on the same system can login using XDM. To enable users on other systems to connect to the display server, edit the access control rules and enable the connection listener. To configure XDM to listen for any remote connection, comment out the DisplayManager.requestPort line in /usr/local/lib/X11/xdm/xdm-config by putting a ! in front of it: ! SECURITY: do not listen for XDMCP or Chooser requests ! Comment out this line if you want to manage X terminals with xdm DisplayManager.requestPort: 0 Save the edits and restart XDM. To restrict remote access, look at the example entries in /usr/local/lib/X11/xdm/Xaccess and refer to &man.xdm.1; for further information. Valentino Vaschetto Contributed by This section describes how to install three popular desktop environments on a &os; system. A desktop environment can range from a simple window manager to a complete suite of desktop applications. Over a hundred desktop environments are available in the x11-wm category of the Ports Collection. GNOME GNOME is a user-friendly desktop environment. It includes a panel for starting applications and displaying status, a desktop, a set of tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. More information regarding GNOME on &os; can be found at http://www.FreeBSD.org/gnome. That web site contains additional documentation about installing, configuring, and managing GNOME on &os;. This desktop environment can be installed from a package: &prompt.root; pkg install gnome3 To instead build GNOME from ports, use the following command. GNOME is a large application and will take some time to compile, even on a fast computer. &prompt.root; cd /usr/ports/x11/gnome3 &prompt.root; make install clean GNOME requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup: proc /proc procfs rw 0 0 GNOME uses D-Bus and HAL for a message bus and hardware abstraction. These applications are automatically installed as dependencies of GNOME. Enable them in /etc/rc.conf so they will be started when the system boots: dbus_enable="YES" hald_enable="YES" After installation, configure &xorg; to start GNOME. The easiest way to do this is to enable the GNOME Display Manager, GDM, which is installed as part of the GNOME package or port. It can be enabled by adding this line to /etc/rc.conf: gdm_enable="YES" It is often desirable to also start all GNOME services. To achieve this, add a second line to /etc/rc.conf: gnome_enable="YES" GDM will start automatically when the system boots. A second method for starting GNOME is to type startx from the command-line after configuring ~/.xinitrc. If this file already exists, replace the line that starts the current window manager with one that starts /usr/local/bin/gnome-session. If this file does not exist, create it with this command: &prompt.user; echo "exec /usr/local/bin/gnome-session" > ~/.xinitrc A third method is to use XDM as the display manager. In this case, create an executable ~/.xsession: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/gnome-session" >> ~/.xsession &prompt.user; chmod +x ~/.xsession KDE KDE is another easy-to-use desktop environment. This desktop provides a suite of applications with a consistent look and feel, a standardized menu and toolbars, keybindings, color-schemes, internationalization, and a centralized, dialog-driven desktop configuration. More information on KDE can be found at http://www.kde.org/. For &os;-specific information, consult http://freebsd.kde.org. To install the KDE package, type: &prompt.root; pkg install x11/kde4 To instead build the KDE port, use the following command. Installing the port will provide a menu for selecting which components to install. KDE is a large application and will take some time to compile, even on a fast computer. &prompt.root; cd /usr/ports/x11/kde4 &prompt.root; make install clean KDE display manager KDE requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup: proc /proc procfs rw 0 0 KDE uses D-Bus and HAL for a message bus and hardware abstraction. These applications are automatically installed as dependencies of KDE. Enable them in /etc/rc.conf so they will be started when the system boots: dbus_enable="YES" hald_enable="YES" The installation of KDE includes the KDE Display Manager, KDM. To enable this display manager, add this line to /etc/rc.conf: kdm4_enable="YES" A second method for launching KDE is to type startx from the command line. For this to work, the following line is needed in ~/.xinitrc: exec /usr/local/bin/startkde A third method for starting KDE is through XDM. To do so, create an executable ~/.xsession as follows: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/startkde" >> ~/.xsession &prompt.user; chmod +x ~/.xsession Once KDE is started, refer to its built-in help system for more information on how to use its various menus and applications. Xfce is a desktop environment based on the GTK+ toolkit used by GNOME. However, it is more lightweight and provides a simple, efficient, easy-to-use desktop. It is fully configurable, has a main panel with menus, applets, and application launchers, provides a file manager and sound manager, and is themeable. Since it is fast, light, and efficient, it is ideal for older or slower machines with memory limitations. More information on Xfce can be found at http://www.xfce.org. To install the Xfce package: &prompt.root; pkg install xfce Alternatively, to build the port: &prompt.root; cd /usr/ports/x11-wm/xfce4 &prompt.root; make install clean Unlike GNOME or KDE, Xfce does not provide its own login manager. In order to start Xfce from the command line by typing startx, first add its entry to ~/.xinitrc: &prompt.user; echo "exec /usr/local/bin/startxfce4 --with-ck-launch" > ~/.xinitrc An alternate method is to use XDM. To configure this method, create an executable ~/.xsession: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/startxfce4 --with-ck-launch" >> ~/.xsession &prompt.user; chmod +x ~/.xsession One way to make using a desktop computer more pleasant is with nice 3D effects. Installing the Compiz Fusion package is easy, but configuring it requires a few steps that are not described in the port's documentation. Desktop effects can cause quite a load on the graphics card. For an nVidia-based graphics card, the proprietary driver is required for good performance. Users of other graphics cards can skip this section and continue with the xorg.conf configuration. To determine which nVidia driver is needed see the FAQ question on the subject. Having determined the correct driver to use for your card, installation is as simple as installing any other package. For example, to install the latest driver: &prompt.root; pkg install x11/nvidia-driver The driver will create a kernel module, which needs to be loaded at system startup. Add the following line to /boot/loader.conf: nvidia_load="YES" To immediately load the kernel module into the running kernel by issuing a command like kldload nvidia, however it has been noted that the some versions of &xorg; will not function properly if the driver is not loaded at boot time. After editing /boot/loader.conf, a reboot is recommended. With the kernel module loaded, you normally only need to change a single line in xorg.conf to enable the proprietary driver: Find the following line in /etc/X11/xorg.conf: Driver "nv" and change it to: Driver "nvidia" Start the GUI as usual, and you should be greeted by the nVidia splash. Everything should work as usual. To enable Compiz Fusion, /etc/X11/xorg.conf needs to be modified: Add the following section to enable composite effects: Section "Extensions" Option "Composite" "Enable" EndSection Locate the Screen section which should look similar to the one below: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" ... and add the following two lines (after Monitor will do): DefaultDepth 24 Option "AddARGBGLXVisuals" "True" Locate the Subsection that refers to the screen resolution that you wish to use. For example, if you wish to use 1280x1024, locate the section that follows. If the desired resolution does not appear in any subsection, you may add the relevant entry by hand: SubSection "Display" Viewport 0 0 Modes "1280x1024" EndSubSection A color depth of 24 bits is needed for desktop composition, change the above subsection to: SubSection "Display" Viewport 0 0 Depth 24 Modes "1280x1024" EndSubSection Finally, confirm that the glx and extmod modules are loaded in the Module section: Section "Module" Load "extmod" Load "glx" ... The preceding can be done automatically with x11/nvidia-xconfig by running (as root): &prompt.root; nvidia-xconfig --add-argb-glx-visuals &prompt.root; nvidia-xconfig --composite &prompt.root; nvidia-xconfig --depth=24 Installing Compiz Fusion is as simple as any other package: &prompt.root; pkg install x11-wm/compiz-fusion When the installation is finished, start your graphic desktop and at a terminal, enter the following commands (as a normal user): &prompt.user; compiz --replace --sm-disable --ignore-desktop-hints ccp & &prompt.user; emerald --replace & Your screen will flicker for a few seconds, as your window manager (e.g. Metacity if you are using GNOME) is replaced by Compiz Fusion. Emerald takes care of the window decorations (i.e. close, minimize, maximize buttons, title bars and so on). You may convert this to a trivial script and have it run at startup automatically (e.g. by adding to Sessions in a GNOME desktop): #! /bin/sh compiz --replace --sm-disable --ignore-desktop-hints ccp & emerald --replace & Save this in your home directory as, for example, start-compiz and make it executable: &prompt.user; chmod +x ~/start-compiz Then use the GUI to add it to Startup Programs (located in System, Preferences, Sessions on a GNOME desktop). To actually select all the desired effects and their settings, execute (again as a normal user) the Compiz Config Settings Manager: &prompt.user; ccsm In GNOME, this can also be found in the System, Preferences menu. If you have selected gconf support during the build, you will also be able to view these settings using gconf-editor under apps/compiz. If the mouse does not work, you will need to first configure it before proceeding. In recent Xorg versions, the InputDevice sections in xorg.conf are ignored in favor of the autodetected devices. To restore the old behavior, add the following line to the ServerLayout or ServerFlags section of this file: Option "AutoAddDevices" "false" Input devices may then be configured as in previous versions, along with any other options needed (e.g., keyboard layout switching). As previously explained the hald daemon will, by default, automatically detect your keyboard. There are chances that your keyboard layout or model will not be correct, desktop environments like GNOME, KDE or Xfce provide tools to configure the keyboard. However, it is possible to set the keyboard properties directly either with the help of the &man.setxkbmap.1; utility or with a hald's configuration rule. For example if, one wants to use a PC 102 keys keyboard coming with a french layout, we have to create a keyboard configuration file for hald called x11-input.fdi and saved in the /usr/local/etc/hal/fdi/policy directory. This file should contain the following lines: <?xml version="1.0" encoding="iso-8859-1"?> <deviceinfo version="0.2"> <device> <match key="info.capabilities" contains="input.keyboard"> <merge key="input.x11_options.XkbModel" type="string">pc102</merge> <merge key="input.x11_options.XkbLayout" type="string">fr</merge> </match> </device> </deviceinfo> If this file already exists, just copy and add to your file the lines regarding the keyboard configuration. You will have to reboot your machine to force hald to read this file. It is possible to do the same configuration from an X terminal or a script with this command line: &prompt.user; setxkbmap -model pc102 -layout fr /usr/local/share/X11/xkb/rules/base.lst lists the various keyboard, layouts and options available. &xorg; tuning The xorg.conf.new configuration file may now be tuned to taste. Open the file in a text editor such as &man.emacs.1; or &man.ee.1;. If the monitor is an older or unusual model that does not support autodetection of sync frequencies, those settings can be added to xorg.conf.new under the "Monitor" section: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" HorizSync 30-107 VertRefresh 48-120 EndSection Most monitors support sync frequency autodetection, making manual entry of these values unnecessary. For the few monitors that do not support autodetection, avoid potential damage by only entering values provided by the manufacturer. X allows DPMS (Energy Star) features to be used with capable monitors. The &man.xset.1; program controls the time-outs and can force standby, suspend, or off modes. If you wish to enable DPMS features for your monitor, you must add the following line to the monitor section: Option "DPMS" xorg.conf While the xorg.conf.new configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the "Screen" section: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultDepth keyword describes the color depth to run at by default. This can be overridden with the -depth command line switch to &man.Xorg.1;. The Modes keyword describes the resolution to run at for the given color depth. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. In the example above, the default color depth is twenty-four bits per pixel. At this color depth, the accepted resolution is 1024 by 768 pixels. Finally, write the configuration file and test it using the test mode given above. One of the tools available to assist you during troubleshooting process are the &xorg; log files, which contain information on each device that the &xorg; server attaches to. &xorg; log file names are in the format of /var/log/Xorg.0.log. The exact name of the log can vary from Xorg.0.log to Xorg.8.log and so forth. If all is well, the configuration file needs to be installed in a common location where &man.Xorg.1; can find it. This is typically /etc/X11/xorg.conf or /usr/local/etc/X11/xorg.conf. &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf The &xorg; configuration process is now complete. &xorg; may be now started with the &man.startx.1; utility. The &xorg; server may also be started with the use of &man.xdm.1;. Intel i810 graphic chipset Configuration with &intel; i810 integrated chipsets requires the agpgart AGP programming interface for &xorg; to drive the card. See the &man.agp.4; driver manual page for more information. This will allow configuration of the hardware as any other graphics board. Note on systems without the &man.agp.4; driver compiled in the kernel, trying to load the module with &man.kldload.8; will not work. This driver has to be in the kernel at boot time through being compiled in or using /boot/loader.conf. widescreen flatpanel configuration This section assumes a bit of advanced configuration knowledge. If attempts to use the standard configuration tools above have not resulted in a working configuration, there is information enough in the log files to be of use in getting the setup working. Use of a text editor will be necessary. Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+, et.al.) formats support 16:10 and 10:9 formats or aspect ratios that can be problematic. Examples of some common screen resolutions for 16:10 aspect ratios are: 2560x1600 1920x1200 1680x1050 1440x900 1280x800 At some point, it will be as easy as adding one of these resolutions as a possible Mode in the Section "Screen" as such: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1680x1050" EndSubSection EndSection &xorg; is smart enough to pull the resolution information from the widescreen via I2C/DDC information so it knows what the monitor can handle as far as frequencies and resolutions. If those ModeLines do not exist in the drivers, one might need to give &xorg; a little hint. Using /var/log/Xorg.0.log one can extract enough information to manually create a ModeLine that will work. Simply look for information resembling this: (II) MGA(0): Supported additional Video Mode: (II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm (II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0 (II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0 (II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz This information is called EDID information. Creating a ModeLine from this is just a matter of putting the numbers in the correct order: ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings> So that the ModeLine in Section "Monitor" for this example would look like this: Section "Monitor" Identifier "Monitor1" VendorName "Bigname" ModelName "BestModel" ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089 Option "DPMS" EndSection Now having completed these simple editing steps, X should start on your new widescreen monitor. I have installed Compiz Fusion, and after running the commands you mention, my windows are left without title bars and buttons. What is wrong? You are probably missing a setting in /etc/X11/xorg.conf. Review this file carefully and check especially the DefaultDepth and AddARGBGLXVisuals directives. When I run the command to start Compiz Fusion, the X server crashes and I am back at the console. What is wrong? If you check /var/log/Xorg.0.log, you will probably find error messages during the X startup. The most common would be: (EE) NVIDIA(0): Failed to initialize the GLX module; please check in your X (EE) NVIDIA(0): log file that the GLX module has been loaded in your X (EE) NVIDIA(0): server, and that the module is the NVIDIA GLX module. If (EE) NVIDIA(0): you continue to encounter problems, Please try (EE) NVIDIA(0): reinstalling the NVIDIA driver. This is usually the case when you upgrade &xorg;. You will need to reinstall the x11/nvidia-driver package so glx is built again.