Xorg supports most common video cards, keyboards, and pointing devices.
Video cards, monitors, and input devices are
automatically detected and do not require any manual
configuration. Do not create xorg.conf
or run a -configure step unless automatic
configuration fails.
If Xorg has been used on this computer before, move or remove any existing configuration files:
#mv /etc/X11/xorg.conf ~/xorg.conf.etc#mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc
Add the user who will run
Xorg to the
video or
wheel group to enable 3D acceleration
when available. To add user
jru to whichever group is
available:
#pw groupmod video -mjru|| pw groupmod wheel -mjru
The TWM window manager is included by default. It is started when Xorg starts:
%startx
On some older versions of FreeBSD, the system console must be set to vt(4) before switching back to the text console will work properly. See Section 5.4.3, “Kernel Mode Setting (KMS)”.
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:
#pw groupmod video -mslurms|| pw groupmod wheel -mslurms
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):
kern.vty=vt
Manual configuration is usually not necessary. Please do not manually create configuration files unless autoconfiguration does not work.
Xorg looks in several
directories for configuration files.
/usr/local/etc/X11/ is the recommended
directory for these files on FreeBSD. Using this directory
helps keep application files separate from operating system
files.
Storing configuration files in the legacy
/etc/X11/ still works. However, this
mixes application files with the base FreeBSD files and is not
recommended.
It is easier to use multiple files that each configure a
specific setting than the traditional single
xorg.conf. These files are stored in
the xorg.conf.d/ subdirectory of the
main configuration file directory. The full path is
typically
/usr/local/etc/X11/xorg.conf.d/.
Examples of these files are shown later in this section.
The traditional single xorg.conf
still works, but is neither as clear nor as flexible as
multiple files in the xorg.conf.d/
subdirectory.
Because of changes made in recent versions of FreeBSD, it is now possible to use graphics drivers provided by the Ports framework or as packages. As such, users can use one of the following drivers available from graphics/drm-kmod.
2D and 3D acceleration is supported on most Intel KMS driver graphics cards provided by Intel.
Driver name: i915kms
2D and 3D acceleration is supported on most older Radeon KMS driver graphics cards provided by AMD.
Driver name: radeonkms
2D and 3D acceleration is supported on most newer AMD KMS driver graphics cards provided by AMD.
Driver name: amdgpu
For reference, please see https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units or https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units for a list of supported GPUs.
3D acceleration is supported on most Intel® graphics up to Ivy Bridge (HD Graphics 2500, 4000, and P4000), including Iron Lake (HD Graphics) and Sandy Bridge (HD Graphics 2000).
Driver name: intel
For reference, see https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units.
2D and 3D acceleration is supported on Radeon cards up to and including the HD6000 series.
Driver name: radeon
For reference, see https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units.
Several NVIDIA drivers are available in the
x11 category of the Ports
Collection. Install the driver that matches the video
card.
For reference, see https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units.
Some notebook computers add additional graphics processing units to those built into the chipset or processor. Optimus combines Intel® and NVIDIA hardware. Switchable Graphics or Hybrid Graphics are a combination of an Intel® or AMD® processor and an AMD® Radeon GPU.
Implementations of these hybrid graphics systems vary, and Xorg on FreeBSD is not able to drive all versions of them.
Some computers provide a BIOS option to disable one of the graphics adapters or select a discrete mode which can be used with one of the standard video card drivers. For example, it is sometimes possible to disable the NVIDIA GPU in an Optimus system. The Intel® video can then be used with an Intel® driver.
BIOS settings depend on the model
of computer. In some situations, both
GPUs can be left enabled, but
creating a configuration file that only uses the main
GPU in the Device
section is enough to make such a system
functional.
Drivers for some less-common video cards can be
found in the x11-drivers directory
of the Ports Collection.
Cards that are not supported by a specific driver might still be usable with the x11-drivers/xf86-video-vesa driver. This driver is installed by x11/xorg. It can also be installed manually as x11-drivers/xf86-video-vesa. Xorg attempts to use this driver when a specific driver is not found for the video card.
x11-drivers/xf86-video-scfb is a similar nonspecialized video driver that works on many UEFI and ARM® computers.
To set the Intel® driver in a configuration file:
/usr/local/etc/X11/xorg.conf.d/driver-intel.conf
Section "Device" Identifier "Card0" Driver "intel" # BusID "PCI:1:0:0" EndSection
If more than one video card is present, the
BusID identifier can be uncommented
and set to select the desired card. A list of video
card bus IDs can be displayed with
pciconf -lv | grep -B3
display.
To set the Radeon driver in a configuration file:
/usr/local/etc/X11/xorg.conf.d/driver-radeon.conf
Section "Device" Identifier "Card0" Driver "radeon" EndSection
To set the VESA driver in a configuration file:
/usr/local/etc/X11/xorg.conf.d/driver-vesa.conf
Section "Device" Identifier "Card0" Driver "vesa" EndSection
To set the scfb driver for use
with a UEFI or ARM® computer:
scfb Video Driver in a
File/usr/local/etc/X11/xorg.conf.d/driver-scfb.conf
Section "Device" Identifier "Card0" Driver "scfb" EndSection
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).
Run xrandr(1) without any parameters to see a list of video outputs and detected monitor modes:
%xrandrScreen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192 DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm 1920x1200 59.95*+ 1600x1200 60.00 1280x1024 85.02 75.02 60.02 1280x960 60.00 1152x864 75.00 1024x768 85.00 75.08 70.07 60.00 832x624 74.55 800x600 75.00 60.32 640x480 75.00 60.00 720x400 70.08 DisplayPort-0 disconnected (normal left inverted right x axis y axis) HDMI-0 disconnected (normal left inverted right x axis y axis)
This shows that the DVI-0 output
is being used to display a screen resolution of
1920x1200 pixels at a refresh rate of about 60 Hz.
Monitors are not attached to the
DisplayPort-0 and
HDMI-0 connectors.
Any of the other display modes can be selected with xrandr(1). For example, to switch to 1280x1024 at 60 Hz:
%xrandr --mode 1280x1024 --rate 60
A common task is using the external video output on a notebook computer for a video projector.
The type and quantity of output connectors varies
between devices, and the name given to each output
varies from driver to driver. What one driver calls
HDMI-1, another might call
HDMI1. So the first step is to run
xrandr(1) to list all the available
outputs:
%xrandrScreen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192 LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm 1366x768 60.04*+ 1024x768 60.00 800x600 60.32 56.25 640x480 59.94 VGA1 connected (normal left inverted right x axis y axis) 1280x1024 60.02 + 75.02 1280x960 60.00 1152x864 75.00 1024x768 75.08 70.07 60.00 832x624 74.55 800x600 72.19 75.00 60.32 56.25 640x480 75.00 72.81 66.67 60.00 720x400 70.08 HDMI1 disconnected (normal left inverted right x axis y axis) DP1 disconnected (normal left inverted right x axis y axis)
Four outputs were found: the built-in panel
LVDS1, and external
VGA1, HDMI1, and
DP1 connectors.
The projector has been connected to the
VGA1 output. xrandr(1) is now
used to set that output to the native resolution of the
projector and add the additional space to the right side
of the desktop:
%xrandr --output VGA1 --auto --right-of LVDS1
--auto chooses the resolution and
refresh rate detected by EDID. If
the resolution is not correctly detected, a fixed value
can be given with --mode instead of
the --auto statement. For example,
most projectors can be used with a 1024x768 resolution,
which is set with
--mode 1024x768.
xrandr(1) is often run from
.xinitrc to set the appropriate
mode when X starts.
To set a screen resolution of 1024x768 in a configuration file:
/usr/local/etc/X11/xorg.conf.d/screen-resolution.conf
Section "Screen" Identifier "Screen0" Device "Card0" SubSection "Display" Modes "1024x768" EndSubSection EndSection
The few monitors that do not have
EDID can be configured by setting
HorizSync and
VertRefresh to the range of
frequencies supported by the monitor.
/usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf
Section "Monitor" Identifier "Monitor0" HorizSync 30-83 # kHz VertRefresh 50-76 # Hz EndSection
The standardized location of keys on a keyboard is called a layout. Layouts and other adjustable parameters are listed in xkeyboard-config(7).
A United States layout is the default. To select
an alternate layout, set the
XkbLayout and
XkbVariant options in an
InputClass. This will be applied
to all input devices that match the class.
This example selects a French keyboard layout with
the oss variant.
/usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf
Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbLayout" "fr" Option "XkbVariant" "oss" EndSection
Set United States, Spanish, and Ukrainian keyboard layouts. Cycle through these layouts by pressing Alt+Shift. x11/xxkb or x11/sbxkb can be used for improved layout switching control and current layout indicators.
/usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf
Section "InputClass" Identifier "All Keyboards" MatchIsKeyboard "yes" Option "XkbLayout" "us, es, ua" EndSection
X can be closed with a combination of keys.
By default, that key combination is not set because it
conflicts with keyboard commands for some
applications. Enabling this option requires changes
to the keyboard InputDevice
section:
/usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf
Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbOptions" "terminate:ctrl_alt_bksp" EndSection
Many mouse parameters can be adjusted with configuration options. See mousedrv(4) for a full list.
The number of buttons on a mouse can be set in the
mouse InputDevice section of
xorg.conf. To set the number of
buttons to 7:
/usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf
Section "InputDevice" Identifier "Mouse0" Option "Buttons" "7" EndSection
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.
Do not create manual configuration files unless required. Unnecessary manual configuration can prevent proper operation.
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:
#Xorg -configure
The configuration file is saved to
/root/xorg.conf.new. Make any changes
desired, then test that file with:
#Xorg -config /root/xorg.conf.new
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/.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.