FreeBSD Handbook
Prev | Chapter 5 The X Window System | Next

# 5.4 X11 Configuration

Contributed by Christopher Shumway.

## 5.4.1 Before Starting

Before configuration of X11 the following information about the target system is needed:

- Monitor specifications

- Video Adapter chipset

- Video Adapter memory

The specifications for the monitor are used by X11 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the monitor or from the manufacturer's website. There are two ranges of numbers that are needed, the horizontal scan rate and the vertical synchronization rate.

The video adapter's chipset defines what driver module X11 uses to talk to the graphics hardware. With most chipsets, this can be automatically determined, but it is still useful to know in case the automatic detection does not work correctly.

Video memory on the graphic adapter determines the resolution and color depth which the system can run at. This is important to know so the user knows the limitations of the system.

## 5.4.2 Configuring X11

As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:

    % startx

Starting with version 7.4, Xorg can use 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 is attempted.

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.

> Note: 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. In Xorg versions up to 7.3, type:

    # Xorg -config xorg.conf.new

Starting with Xorg 7.4 and above, this test produces a black screen which may make it difficult to diagnose whether X11 is working properly. The older behavior is still available by using the `retro` option:

    # 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, just press Ctrl+Alt+Backspace simultaneously.

> Note: This key combination was enabled by default up to Xorg version 7.3. To enable it in version 7.4 and later, 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.

If the mouse does not work, you will need to first configure it before proceeding. See Section 2.10.10 in the FreeBSD install chapter. Additionally, starting with version 7.4, 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).

> Note: As previously explained since version 7.4, by default, the hald daemon will 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.

Next, tune the `xorg.conf.new` configuration file to taste. Open the file in a text editor such as emacs(1) or ee(1). First, add the frequencies for the target system's monitor. These are usually expressed as a horizontal and vertical synchronization rate. These values are added to the `xorg.conf.new` file under the `"Monitor"` section:

    Section "Monitor"
            Identifier   "Monitor0"
            VendorName   "Monitor Vendor"
            ModelName    "Monitor Model"
            HorizSync    30-107
            VertRefresh  48-120
    EndSection

The `HorizSync` and `VertRefresh` keywords may be missing in the configuration file. If they are, they need to be added, with the correct horizontal synchronization rate placed after the `HorizSync` keyword and the vertical synchronization rate after the `VertRefresh` keyword. In the example above the target monitor's rates were entered.

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.

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

## 5.4.3 Advanced Configuration Topics

### 5.4.3.1 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`.

### 5.4.3.2 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.

Prev | Home | Next
Installing X11 | Up | Using Fonts in X11

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.