6.4. X11 Configuration

Contributed by Christopher Shumway.

6.4.1. Before Starting

In most cases, X11 is self-configuring. Those with older or unusual equipment may find it helpful to gather some hardware information before beginning configuration.

  • Monitor sync frequencies

  • Video card chipset

  • Video card memory

Screen resolution and refresh rate are determined by the monitor's horizontal and vertical sync frequencies. Almost all monitors support electronic autodetection of these values. A few monitors do not provide these values, and the specifications must be determined from the printed manual or manufacturer web site.

The video card chipset is also autodetected, and used to select the proper video driver. It is beneficial for the user to be aware of which chipset is installed for when autodetection does not provide the desired result.

Video card memory determines the maximum resolution and color depth which can be displayed.

6.4.2. Configuring X11

Xorg uses HAL to autodetect keyboards and mice. The sysutils/hal and devel/dbus ports are installed as dependencies of x11/xorg, but must be enabled by the following entries in the /etc/rc.conf file:

hald_enable="YES" dbus_enable="YES"

These services should be started (either manually or by rebooting) before further Xorg configuration or use is attempted.

Xorg can often work without any further configuration steps by simply typing at prompt:

% startx

The automatic configuration may fail to work with some hardware, or may not set things up quite as desired. In these cases, manual configuration will be necessary.


Desktop environments like GNOME, KDE or Xfce have tools allowing the user to easily set the screen parameters such as the resolution. So if the default configuration is not acceptable and you planned to install a desktop environment then just continue with the installation of the desktop environment and use the appropriate screen settings tool.

Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:

# Xorg -configure

This will generate an X11 configuration skeleton file in the /root directory called xorg.conf.new (whether you su(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.

The next step is to test the existing configuration to verify that Xorg can work with the graphics hardware on the target system. Type:

# Xorg -config xorg.conf.new -retro

If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, switch to the virtual console used to start it by pressing Ctrl+Alt+Fn (F1 for the first virtual console) and press Ctrl+C.


The Ctrl+Alt+Backspace key combination may also be used to break out of Xorg. To enable it, you can either type the following command from any X terminal emulator:

% setxkbmap -option terminate:ctrl_alt_bksp

or 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.XkbOptions" type="string">terminate:ctrl_alt_bksp</merge> </match> </device> </deviceinfo>

You will have to reboot your machine to force hald to read this file.

The following line will also have to be added to xorg.conf.new, in the ServerLayout or ServerFlags section:

Option "DontZap" "off"

If the mouse does not work, you will need to first configure it before proceeding. See Section 3.10.9, “Mouse Settings” in the FreeBSD install chapter. 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 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:

% setxkbmap -model pc102 -layout fr

The /usr/local/share/X11/xkb/rules/base.lst file lists the various keyboard, layouts and options available.

The xorg.conf.new configuration file may now be tuned to taste. Open the file in a text editor such as emacs(1) or 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 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"

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 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 X11 log files, which contain information on each device that the X11 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 Xorg(1) can find it. This is typically /etc/X11/xorg.conf or /usr/local/etc/X11/xorg.conf.

# cp xorg.conf.new /etc/X11/xorg.conf

The X11 configuration process is now complete. Xorg may be now started with the startx(1) utility. The X11 server may also be started with the use of xdm(1).

6.4.3. Advanced Configuration Topics Configuration with Intel® i810 Graphics Chipsets

Configuration with Intel® i810 integrated chipsets requires the agpgart AGP programming interface for X11 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. Adding a Widescreen Flatpanel to the Mix

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.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.