Chapter 5. The X Window System

Xorg supports most common video cards, keyboards, and pointing devices.

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, pw(8) is used to add user slurms to the video group, or to the wheel group if there is no video group:

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 FreeBSD use 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 vt(4) console avoids this problem.

Add this line to /boot/loader.conf to enable vt(4):

Manual configuration is usually not necessary. Please do not manually create configuration files unless autoconfiguration does not work.

The Ports framework provides the drm graphics drivers necessary for X11 operation on recent hardware. Users can use one of the following drivers available from graphics/drm-kmod. These drivers use interfaces in the kernel that are normally private. As such, it is strongly recommended that the drivers be built via the ports system via the PORTS_MODULES variable. With PORTS_MODULES, every time you build the kernel, the corresponding port(s) containing kernel modules are re-built against the updated sources. This ensures the kernel module stays in-sync with the kernel itself. The kernel and ports trees should be updated together for maximum compatibility. You can add PORTS_MODULES to your /etc/make.conf file to ensure all kernels you build rebuild this module. Advanced users can add it to their kernel config files with the makeoptions directive. If you run GENERIC and use freebsd-update, you can just build the graphics/drm-kmod or x11/nvidia-driver port after each freebsd-update install invocation.

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 xrandr(1).

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.

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:

The configuration file is saved to /root/xorg.conf.new. Make any changes desired, then test that file (using -retro so there is a visible background) with:

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 X(7) manual page or TrueType® Fonts.

To install the above Type1 font collections from binary packages, run the following commands:

Alternatively, to build from the Ports Collection, run the following commands:

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:

Alternatively, at the command line in the X session run:

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 Anti-Aliased Fonts.

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.

Now make a directory for the TrueType® fonts (for example, /usr/local/shared/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 mkfontscale to create a fonts.dir, so that the X font renderer knows that these new files have been installed. mkfontscale can be installed as a package:

Then create an index of X font files in a directory:

Now add the TrueType® directory to the font path. This is just the same as described in Type1 Fonts:

or add a FontPath line to xorg.conf.

Now Gimp, LibreOffice, 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 LibreOffice) will look much better now.

All fonts in Xorg that are found in /usr/local/shared/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 fonts-conf(5).

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:

As previously stated, all fonts in /usr/local/shared/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:

After adding new fonts, and especially new font directories, rebuild the font caches:

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:

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:

(this aliases the other common names for fixed fonts as "mono"), and then add:

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:

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.

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:

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:

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/etc/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. XDM Configuration Files summarizes the function of each of these files. The exact syntax and usage of these files is described in xdm(1).

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/etc/X11/xdm/xdm-config by putting a ! in front of it:

Save the edits and restart XDM. To restrict remote access, look at the example entries in /usr/local/etc/X11/xdm/Xaccess and refer to xdm(1) for further information.

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 FreeBSD can be found at https://www.FreeBSD.org/gnome. That web site contains additional documentation about installing, configuring, and managing GNOME on FreeBSD.

This desktop environment can be installed from a package:

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.

GNOME requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup:

GNOME uses D-Bus 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:

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:

It is often desirable to also start all GNOME services. To achieve this, add a second line to /etc/rc.conf:

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:

A third method is to use XDM as the display manager. In this case, create an executable ~/.xsession:

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 FreeBSD-specific information, consult http://freebsd.kde.org.

To install the KDE package, type:

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.

KDE requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup:

KDE uses D-Bus 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:

Since KDE Plasma 5, the KDE Display Manager, KDM is no longer developed. A possible replacement is SDDM. To install it, type:

Add this line to /etc/rc.conf:

A second method for launching KDE Plasma is to type startx from the command line. For this to work, the following line is needed in ~/.xinitrc:

A third method for starting KDE Plasma is through XDM. To do so, create an executable ~/.xsession as follows:

Once KDE Plasma 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:

Alternatively, to build the port:

Xfce uses D-Bus for a message bus. This application is automatically installed as dependency of Xfce. Enable it in /etc/rc.conf so it will be started when the system boots:

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 create ~/.xinitrc with this command:

An alternate method is to use XDM. To configure this method, create an executable ~/.xsession:

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:

The driver will create a kernel module, which needs to be loaded at system startup. Add the following line to /boot/loader.conf:

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:

and change it to:

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:

Locate the "Screen" section which should look similar to the one below:

and add the following two lines (after "Monitor" will do):

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:

A color depth of 24 bits is needed for desktop composition, change the above subsection to:

Finally, confirm that the "glx" and "extmod" modules are loaded in the "Module" section:

The preceding can be done automatically with x11/nvidia-xconfig by running (as root):

Installing Compiz Fusion is as simple as any other package:

When the installation is finished, start your graphic desktop and at a terminal, enter the following commands (as a normal user):

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):

Save this in your home directory as, for example, start-compiz and make it executable:

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:

If you have selected "gconf support" during the build, you will also be able to view these settings using gconf-editor under apps/compiz.

Configuration with Intel® i810 integrated chipsets requires the agpgart AGP programming interface for Xorg to drive the card. See the 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 agp(4) driver compiled in the kernel, trying to load the module with 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.

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:

At some point, it will be as easy as adding one of these resolutions as a possible Mode in the Section "Screen" as such:

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:

This information is called EDID information. Creating a ModeLine from this is just a matter of putting the numbers in the correct order:

So that the ModeLine in Section "Monitor" for this example would look like this:

Now having completed these simple editing steps, X should start on your new widescreen monitor.