Understanding the xorg.conf File

Understanding the `xorg.conf` File

Like most other components of FreeBSD, the X11 configuration is controlled by a configuration file that is in plain text. The primary X11 configuration file is located in /etc/X11 and is called xorg.conf. This is the file that is created or modified by xorgcfg (the menubased interface for X11 configuration you used back in Chapter 2) and also by xorgconfig (the text-based configuration script that was covered in the previous sections of this chapter). These configuration tools have made X11 configuration much easier than it used to be when the files had to be created and edited entirely by hand.

However, there are still some situations in which you might need to make changes to the configuration file by hand. For example, if your video card was not listed in the card database, you might need to make manual changes to this file to fine-tune it to your card's capabilities. Another situation in which you may need to make changes by hand is if you want to make changes to aspects of X11 that xorgconfig doesn't address, such as the acceleration or speed settings for the mouse. If you simply want to make one or two minor changes to X11, it may be desirable to edit the file by hand rather than go through a complete configuration with xorgconfig.

To make changes to the xorg.conf file, first make a backup copy of the file so that it will be easy to undo your changes if they cause problems. For example, you might want to copy /etc/X11/xorg.conf to /etc/X11/xorg.conf.bak. After you have a backup copy, open the file /etc/X11/xorg.conf in your favorite text editor (see Chapter 6 if you need information on how to use one of the text editors included with FreeBSD).

`xorg.conf` Syntax

The xorg.conf file is divided into several sections. Each section relates to a specific device or configuration issue, and begins with the keyword Section followed by the section name in quotes. Each section ends with the keyword EndSection. The body of the section is indented for easy readability. Comments, or lines that are ignored by X11, begin with a pound sign (#). The following is an example of a section in the xorg.conf file:

Section "Module" # This loads the DBE extension module.     Load        "dbe"   # Double buffer extension # This loads the miscellaneous extensions module, and disables # initialization of the XFree86-DGA extension within that module.     SubSection  "extmod"       Option    "omit xfree86-dga"   # don't initialize the DGA extension     EndSubSection # This loads the font modules     Load        "type1" #    Load        "speedo"     Load        "freetype" #    Load        "xtt" # This loads the GLX module #    Load       "glx" # This loads the DRI module #    Load       "dri" EndSection

The comments before this section are not shown, but in the xorg.conf file, they explain what the section is for. In this case the Module section loads dynamic modules when the server starts to support various components of the system. For example, the part of this example that begins with # This loads the font modules loads dynamic modules to support various types of fonts. In this case, the first Load line loads a module that supports Adobe Type 1 fonts. The second active Load line loads the freetype module, which is a freely available module that allows X11 to use commercial TrueType fonts.

In addition to main sections, there are also subsections that can be embedded within the sections. These begin with the keyword SubSection followed by the name of the subsection in quotes, and end with the keyword EndSubSection. Like the main sections, they are also indented for readability purposes.

The next few sections of this chapter take a look at the various sections and subsections in the xorg.conf file.

Section `"Module"`

The Module section is where modules can be dynamically loaded to support X11 components such as various font types. Dynamically loaded modules are not a part of the X binary; instead, these modules are loaded as needed when X11 starts. The advantage of dynamically loaded modules is that they are loaded only if they are needed. Modules that are not needed are not loaded and therefore do not waste memory and system resources. For example, if you don't have any TrueType fonts on your system, there is little point in having TrueType font support in X11, and you can comment out the Load "freetype" line.

Modules that are to be loaded begin with the keyword Load followed by the name of the module in quotes. For example, the following line loads the module that supports TrueType fonts:

Load "freetype"

Section `"Files"`

This section is similar to the X11 PATH environment variable. The Files section tells X11 where in the system it can expect to find various required files.

The only portion of this section you may ever want to modify is that which tells X11 where to look for fonts. Each one of the font directories begins with the keyword FontPath, followed by a directory enclosed in quotation marks. For example, the following line is where the Adobe Type 1 fonts are located:

FontPath   "/usr/X11R6/lib/X11/fonts/Type1/"

This is the directory in which you would install new Adobe Type 1 fonts that you may download or purchase. Details on X11 fonts will be covered later on in this chapter, in the section titled "Working with Fonts."

If you do add new font directories, the name of the directory is not really important. For example, there is nothing that says that Adobe Type 1 fonts have to be stored in a directory called Type1. This convention is just followed to make it easier for you to guess what types of fonts are in a directory.

Section `"ServerFlags"`

The ServerFlags section of the file contains some global options that control the behavior of X11. Some of the available options are present in the configuration file generated by xorgconfig and include comments about what they do. All the options are commented out by default.

All the options in this section begin with the keyword Option, followed by the option in quotes. For example, the following line will disable the Ctrl+Alt+Backspace sequence that kills the X Server immediately:

Option "DontZap"

The following subsections discuss some (though not all) of the options available in ServerFlags you're most likely to use.

Option `"NoTrapSignals"`

If this option is uncommented (enabled), X11 will not exit cleanly when there is a problem. Instead, it will write a core dump file. This can cause problems with the console not working correctly after X11 has terminated incorrectly.

You should probably leave this line commented out unless you are experiencing consistent X Server crashes. In that case, uncommenting this option creates a core dump file that is invaluable for troubleshooting purposes. Even if you are not a programmer and cannot make heads or tails of the dump file, it will be an important piece of evidence if you want to file a bug report with the Xorg project developers.

Option `"DontZap"`

If this option is uncommented, you will not be able to kill the X Server by using the Ctrl+Alt+Backspace key combination. You should definitely not uncomment this line until you have tested your X11 configuration and are sure it is working correctly. This option is helpful if you're setting up a kiosk or a public computer where it's important that users not have the ability to exit from the running application or escape from the X11 session.

Option `"DontZoom"`

If this option is uncommented, it will disable video mode switching using Ctrl+Alt++ and Ctrl+Alt+ (on the numeric keypad). By default, these key combinations will allow you to cycle between different video modes if you have configured multiple video resolutions.

About the only reason for uncommenting this would be if you have programs that require these key combinations for some other use. In this case, uncommenting this line will prevent the X Server from intercepting the combination and causing the video modes to switch in the middle of your work.

Option `"DisableVidModeExtension"`

If this option is uncommented, it will prevent the xvidtune program from making any changes to the video system. If this is a multiuser system, it may be a good idea to uncomment this line to prevent users from being able to use xvidtune because the improper use of xvidtune can damage your monitor. Note that if the line is uncommented, xvidtune can still be loaded. But you will not be able to make any changes to the video system with it.

Most of the other options in this section that are present in the configuration file generated by xorgconfig should probably be left alone.

Other Options Not Present by Default for Section `"ServerFlags"`

Several other options may be of interest that are not present in the default configuration file generated by xorgconfig. We are not going to discuss all of them here, but many of the more useful ones are listed. If you want to add any of these following options, simply add the line in bold text to the ServerFlags section in xorg.conf:

Option "AllowMouseOpenFail" By default, if the X Server cannot communicate with the mouse or other pointing device, the server will not start and will exit with an error. Adding this line will allow the server to start, even if the mouse or other pointing device cannot be accessed.
Unless you are trying to use X11 without a mouse or other pointing device, there is probably no reason to change this option.
Option "BlankTime" "n" This option will cause the screen to go blank after the number of minutes represented by n. If this option is not present, the default is 10 minutes.
Option "StandbyTime "n" This option will cause the monitor to go into standby mode after the number of minutes represented by n. If this option is not present, the default is 20 minutes.
This option is not supported by all video drivers, and it only works with monitors that support DPMS power-saving features. The Monitor section of xorg.conf (discussed later in this chapter) must explicitly specify that the monitor can support DPMS for this feature to apply.
Option "SuspendTime" "n" This option will cause the monitor to go into suspend mode after the number of minutes represented by n. If this option is not present, the default is 30 minutes.
This option is not supported by all video drivers, and it only works with monitors that support DPMS power-saving features. The Monitor section of xorg.conf (discussed later in this chapter) must explicitly specify that the monitor can support DPMS for this feature to apply.
Option "OffTime" "n" This option will turn the monitor off after the number of minutes represented by n. If this option is not present, the default is 40 minutes.
This option is not supported by all video drivers, and it only works with monitors that support DPMS power-saving features. The Monitor section of xorg.conf (discussed later in this chapter) must explicitly specify that the monitor can support DPMS for this feature to apply.
Option "NoPM" This option will disable some events that relate to power management. By default, power management is enabled on systems that can support it. You should need to add this option only if you are experiencing strange problems that seem to be related to power-management events.

A few other options can be included in this section, but they are less commonly used. If you are interested in some of the other options available, see the man page for xorg.conf.

Section `"InputDevice"`

This section is where the input devices are configured. There can be multiple InputDevice sections in the configuration file. Usually there will be at least two: one for the keyboard and one for the mouse or other pointing device.

InputDevice sections have several keywords associated with them. The first is the Identifier keyword. It is followed by a name that identifies this device. X11 doesn't really care what you call the device, but it is best to use a descriptive name that defines it well enough for your own purposes.

The second is the Driver keyword. It is followed by the name of the driver for this device, in quotes. The most common drivers are "keyboard" and "mouse", but there are a few others such as "microtouch" for a touch screen.

The final part of the InputDevice section consists of options for the device.

The following sections look at the two most common InputDevice sectionsthe keyboard and the mouseand discuss some of the option lines available for configuring them.

Configuring the Keyboard Options

Here is an example of the first part of the InputDevice section for the keyboard:

Section "InputDevice"     Identifier  "Keyboard1"     Driver      "kbd"

You can choose from a number of available options for controlling keyboard behavior. Here are some of the most commonly used of these options:

Option "Protocol" If this option is omitted or commented out, the default value of "Standard" will be used. There is probably no reason to change this.
Option "AutoRepeat" "x y" This option controls the repeat rate of the keys on the keyboard. The number represented by x is the delay in milliseconds before the key starts repeating. The number represented by y is the number of times per second that the key will repeat.
The default is 500 milliseconds before the key starts to repeat, and 30 times per second that it will repeat.
Option "XkbRules" "xorg" This option determines the way various aspects of the keyboard are interpreted. In most cases, you should leave this set to "xorg" unless you chose an atypical keyboard type in the xorgconfig script.
Option "XkbModel" "pc104" If you have a 105-key Windows keyboard, this will be "pc105". If you have a 101-key keyboard that does not have the Windows keys, it will be "pc101". These values will also work for laptops. Even though laptops usually have fewer keys, they generally have ways of emulating the additional keys.
Option "XkbLayout" "us" This will usually be set to "us". If you are using the Japanese PC-98 platform, you will want to change it to "nec/jp". Again, running xorgconfig is probably the best way to set this option for your needs.
Option "XkbOptions" "ctrl:swapcaps" If this line is uncommented, it will cause the Caps Lock key to become a Ctrl key and the left Ctrl key to become a Caps Lock key. You may want to uncomment this line if you are an Emacs guru (Emacs relies heavily on the Ctrl key) or if you are used to a UNIX keyboard layout in which the Ctrl key is placed in the position where the Caps Lock key is found on PC keyboards.

Configuring Mouse Options

Here is an example of the first part of the InputDevice section for the mouse:

Section "InputDevice" # Identifier and driver     Identifier  "Mouse1"     Driver      "mouse"     Option "Protocol"    "Auto"     Option "Device"      "/dev/sysmouse"

The following subsections describe some of the most commonly used options.

Option "Protocol" "protocol" In this option, protocol represents the type of mouse that your system has. This option is required, and the X Server will not work if it is not present.
Many users will be able to get away with specifying Auto here to have the X Server automatically attempt to determine the protocol the mouse uses. This usually causes no problems these days; but if it does, several other options are available. A few of the more useful protocol types follow:
- The Logitech protocol is used only by very old Logitech serial mice. If you have a newer Logitech serial mouse, use the Microsoft or MouseMan protocols.
- Use the PS/2 protocol for any PS/2 mouse, no matter who the manufacturer is. You have a PS/2 mouse if the mouse connector is a small round one.
- If you have a laptop or notebook system, the built-in pointing device (such as a touchpad or trackpoint) will probably work with the PS/2 protocol.
  I suggest that you try using Auto first and then change it only if your mouse is not detected or is not working properly.
Option "Device" "devicename" This option specifies what device the mouse is driven by. The option is required, and the X Server will not work if this option is missing.
Table 7.1 (earlier in this chapter) lists some of the common device names where your mouse may be located.
Note that devicename in this option should be replaced with the mouse device.
Option "Buttons" "n" In most cases, the number of buttons on the mouse will be automatically detected; if they are not, this option can be used to tell the X Server how many buttons are on the mouse.
Here, n represents the number of buttons the mouse has. The most common values are 2 and 3, although numbers up to 5 are supported. If you happen to have a mouse with five buttons on it, go for it.
Option "Emulate3Buttons" This very important line allows a two-button mouse to emulate a three-button mouse. If you have a two-button mouse, you will want to uncomment this line because X11 makes extensive use of all three mouse buttons.
If you do uncomment this line, the middle mouse button is emulated by pressing the left and right mouse buttons at the same time (a "chord").
Option "Emulate3Timeout" "n" If the Emulate3Buttons option is enabled, this option will control the number of milliseconds that can elapse between clicking the left and right mouse buttons before X11 will no longer interpret the action to be a middle click. In other words, both the left and right mouse buttons must be pushed within this time frame in order for the action to be interpreted as a middle click. Here, n is the number of milliseconds that can elapse.
If this line is not present and the Emulate3Buttons option is enabled, the default Emulate3Timeout value will be 50 milliseconds.

Section `"Monitor"`

This is where you configure the horizontal and vertical refresh rates for your monitor. It consists of the Identifier keyword followed by a name in quotes to identify this monitor. The name you choose is not very important.

Two other keywords are required to be present in this section: HorizSync and VertRefresh. You learn more about them in the following sections. A few other options can be used with the Monitor section, but they are not as common. For full details on all the available options, see the man page for xorg.conf.

`HorizSync`

HorizSync is the horizontal sync rate in kilohertz that the monitor supports. It can be specified in several ways:

As a range This is normally the method used to configure multisync monitors (and virtually all CRT monitors are multisync these days). For example, HorizSync 44-76 would be used for a monitor that can support horizontal refresh rates ranging from 44 to 76 kilohertz.
As a single value If you have a fixed frequency monitor that supports only one frequency, it is simply listed after HorizSync (for example, HorizSync 35.2).
As a list of frequencies If your monitor supports several fixed frequencies, you can supply a list of the fixed frequencies that it supports, separated by commas (for example "HorizSync 31.5, 35.2").
As multiple ranges of frequencies If your monitor supports more than one range of frequencies but has a gap in the middle that it does not support, you can list multiple ranges (for example, "HorizSync 15-25, 30-50").

`VertRefresh`

The VertRefresh keyword lists the vertical refresh rate your monitor can support. It can take its value in any of the same formats that the HorizSync keyword can use.

Caution

Supplying values for HorizSync and VertRefresh that are outside the range of what your monitor can support can damage or destroy your monitor. Be extremely careful that you do not supply values outside the supported range. See your monitor's documentation or check the manufacturer's website (or the http://www.monitorworld.com/Monitors/database) for technical specifications to find the values your monitor can support.

Section `"Device"`

This section is where you configure your graphics adapter (video card). Like most other sections, it begins with the keyword Identifier, followed by a name in quotes to identify the device.

The Driver keyword is also required, followed by the name of the driver for your card in quotes. For example, if you have an NVIDIA TNT2, the line would look like this:

Driver "nv"

If you have a supported video card, it is much easier to go through xorgconfig (explained earlier in this chapter) to set up the graphics device than to do it manually in the xorg.conf file. However, if for whatever reason you need to or want to do it manually, a full list of the supported cards, along with the driver that should be used to support each card, is available at http://wiki.x.org/wiki/VideoDrivers or in Appendix B, "Hardware Compatibility Lists."

The other keyword that is most commonly used here is the VideoRam keyword to specify how much video RAM the video card has. For example, if your video card has 16MB of RAM, the line would look like this:

VideoRam 16384

As you learned earlier, the amount of video RAM is specified in kilobytes; in binary math, a kilobyte is actually 1,024 bytes. Be sure to multiply your card's megabyte value by 1,024 to get the value you have to specify in the configuration file.

Some more options are available for graphics devices, but most of them will not be needed for most video cards. See the man page for xorg.conf for full details on all the available options.

Also, you will probably want to have a look at the web page located at http://x.org/X11R6.8.2/doc/RELNOTES3.html#9 to see whether there are any notes regarding your particular type of video card and any specific options you need to supply for it.

Tip

If you cannot find a driver for your video card, all may not be lost. You might be able to get the card working with the VESA driver. VESA is a generic Super VGA specification that a lot of cards support to some extent. If you have to use this driver, the accelerated features of your card will not be fully supported, and nor will all the resolutions and color depths that your video card can handle. But it's better than nothing, and it may allow you to use a card for which there is no driver currently available for X11. If you end up using this alternative, check the supported card database often because support for new cards is being added on a regular basis.

Section `"Screen"`

The Screen section is where a monitor is combined with a graphics card to make a "display" construct that will work with the X Server. It starts with the Identifier keyword that contains a name enclosed in quotes, identifying this particular combination of monitor and video card. There can be multiple Screen sections present in the xorg.conf file, but there must be at least one. The first one encountered will be the one that is used unless specified otherwise in the ServerLayout section.

After you have specified an identifier for the Screen section, you also must specify the "devicename", "monitorname", and DefaultDepth "n" keywords. Other available options are rarely used; see the man page for xorg.conf for details on these options.

Device "devicename" This is the name of the graphics device (video card) that should be used for this screen configuration. Here, devicename is whatever string appears in the Identifier section of the graphics device that you set up earlier in the file.
Monitor "monitorname" This is the name of the monitor that should be used for this screen configuration. Here, monitorname is whatever string appears in the Identifier section of the monitor that you set up earlier in the file.
DefaultDepth "n" This is the default color depth that should be used for this screen configuration. Valid values for n are 8, 16, and 24, assuming your video card supports all three color depths.

SubSection `"Display"`

After you have configured the Screen section, you will need to configure the Display subsection(s) for the screen, to specify the resolutions and cycle order for each available color depth. There must be at least one Display subsection for the default color depth, or the X Server will not start. However, there can be more than one Display subsection, one for each color depth.

The first line in the subsection will be the keyword Depth followed by the color depth that this subsection is for. Here is an example of what the first two lines of this subsection might look like:

Subsection "Display"     Depth       24

The third line that is required here is a mode line. It is simply the keyword Modes followed by a list of the resolutions you want to have supported. The first resolution listed will be the default. The resolutions listed after that will be cycled through when the Ctrl+Alt++ and Ctrl+Alt+ key combinations (using the keypad) are used. Note that this may not work on some systems.

Here is a sample mode line:

Modes "1024x768" "800x600" "640x480"

In this example, the default resolution will be 1024x768 for this color depth. Pressing Ctrl+Alt++ or Ctrl+Alt+ will cause X11 to switch to 800x600 and 640x480, in order.

X11 allows you to have a virtual screen that is larger than the resolution you have configured. For example, you can have your screen resolution set to 800x600 and have a virtual screen size of 1024x768. This was discussed in a previous section of this chapter when we talked about configuring X11 with the xorgconfig program.

If you decide that you want to use a virtual screen, you can use the "Virtual resolution" option to configure the resolution the virtual screen should be. For example, "Virtual 1024x768" will set the virtual screen size to 1024x768. If the actual screen resolution is lower than this, only part of the screen will be visible. To see the portions of the screen that are not visible, you will need to drag the mouse pointer off the edge of the screen. This will scroll the screen left, right, up, or down, depending on which edge of the screen you are interacting with.

Some other options are available here but are not commonly used. For a list of all the options available in the Display subsection, see the man page for xorg.conf.

Section `"ServerLayout"`

The ServerLayout section is optional. If it does not exist, the first screen listed and the first keyboard and mouse input devices listed will be used. If the ServerLayout section does exist, it is used to select from among multiple screen entries and keyboard and mouse entries to be used during your X session.

The Identifier keyword is required, and it is followed by a string in quotes that gives this server layout a name. Here are some of the other items commonly used in the ServerLayout section:

Screen "screenname" This is the screen configuration that should be used for this device. Here, screenname is the name listed in the Identifier keyword for the Screen section that is to be used for this server layout.
InputDevice "keyboardname" "CoreKeyboard" This determines which keyboard entry should be used for this server layout. Here, keyboardname is the name listed in the Identifier keyword for the Keyboard section you want to use.
The CoreKeyboard option that follows sets this keyboard to the default keyboard.
InputDevice "mousename" "CorePointer" This is like the Keyboard entry, except that it determines the mouse entry that should be used for this server layout. Once again, the CorePointer option that follows sets this mouse to the default mouse.

Option lines can also be included in the ServerLayout section. If they are included and they conflict with options listed in other sections, the options listed here will override the other options.

Other options are available for all aspects of the xorg.conf file, but most of them are rarely used. Once again, see the man page for xorg.conf for full details of all the available configuration options.