6.4. Xorg Configuration

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

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.1. Caveats

The ability to configure optimal resolution is dependent upon the video hardware and the support provided by its driver. At this time, driver support is as follows:

  • NVIDIA: several NVIDIA drivers are available in the x11 category of the FreeBSD Ports Collection. Install the driver that matches the model of the NVIDIA hardware.

  • Intel: as of FreeBSD 9.1, 3D acceleration on most Intel graphics, including IronLake, SandyBridge, and IvyBridge, is supported. Due to the current KMS implementation, it is not possible to switch between the graphical console and a virtual console using Crtl+Alt+F#.

  • ATI/Radeon: 3D acceleration will not work on ATI or Radeon cards until FreeBSD completes its TTM work. These cards will need to be configured with the 2D driver, and if that does not work, with the Vesa driver.

  • Optimus: currently there is no switching support between the two graphics adapters provided by Optimus. Optimus implementations vary, so FreeBSD may or may not be able to successfully load a graphics driver on all hardware. If you get a blank screen, check if the BIOS has an option to disable one of the graphics adapters or to set discrete mode.

6.4.2. Configuring Xorg

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


Start these services before configuring Xorg:

# service hald start
# service dbus start

Once these services are started, check if Xorg auto-configures itself by typing:

# Xorg -configure

This will generate a file named /root/xorg.conf.new which attempts to load the proper drivers for the detected hardware. Next, test that the automatically generated configuration file works with the graphics hardware by typing:

# 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">
    <match key="info.capabilities" contains="input.keyboard">
	  <merge key="input.x11_options.XkbOptions" type="string">terminate:ctrl_alt_bksp</merge>

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 test is unsuccessful, skip ahead to Section 6.8, “Troubleshooting”. Once the test is successful, copy the configuration file to /etc/X11/xorg.conf:

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


Desktop environments like GNOME, KDE or Xfce provide graphical tools to set parameters such as video resolution. If the default configuration works, skip to Section 6.7, “Desktop Environments” for examples on how to install a desktop environment.

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