path: root/documentation/content/en/books/handbook/x11/_index.adoc

---
title: Chapter 5. The X Window System
part: Part I. Getting Started
prev: books/handbook/ports
next: books/handbook/partii
description: This chapter describes how to install and configure Xorg on FreeBSD, which provides the open source X Window System used to provide a graphical environment
tags: ["X11", "Xorg", "TrueType", "DE", "KDE", "Plasma", "Xfce", "Gnome", "XDM", "SDDM", "GDM", "KMS", "Intel", "AMD", "NVIDIA", "Anti-Aliased"]
showBookMenu: true
weight: 7
path: "/books/handbook/"
aliases: [
"/en/books/handbook/x-understanding/",
"/en/books/handbook/x-install/",
"/en/books/handbook/x-config/",
"/en/books/handbook/x-fonts/",
"/en/books/handbook/x-xdm/",
"/en/books/handbook/x11-wm/",
"/en/books/handbook/x-compiz-fusion/",
"/en/books/handbook/x11-troubleshooting/"
]
---

[[x11]]
= The X Window System
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 5
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/handbook/x11/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[x11-synopsis]]
== Synopsis

An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface.
This chapter describes how to install and configure Xorg, which provides the open source X Window System used to provide a graphical environment.
It then describes how to find and install a desktop environment or window manager.

[NOTE]
====
Users who prefer an installation method that automatically configures the Xorg should refer to https://ghostbsd.org[GhostBSD], https://www.midnightbsd.org[MidnightBSD] or https://nomadbsd.org[NomadBSD].
====

For more information on the video hardware that Xorg supports, refer to the http://www.x.org/[x.org] website.

After reading this chapter, you will know:

* The various components of the X Window System, and how they interoperate.
* How to install and configure Xorg.
* How to install and configure several window managers and desktop environments.
* How to use TrueType(R) fonts in Xorg.
* How to set up your system for graphical logins (XDM).

Before reading this chapter, you should:

* Know how to install additional third-party software as described in crossref:ports[ports,Installing Applications: Packages and Ports].

[[x-understanding]]
== Terminology

While it is not necessary to understand all of the details of the various components in the X Window System and how they interact, some basic knowledge of these components can be useful.

X server::
X was designed from the beginning to be network-centric, and adopts a "client-server" model.
In this model, the "X server" runs on the computer that has the keyboard, monitor, and mouse attached.
The server's responsibility includes tasks such as managing the display, handling input from the keyboard and mouse, and handling input or output from other devices such as a tablet or a video projector.
This confuses some people, because the X terminology is exactly backward to what they expect.
They expect the "X server" to be the big powerful machine down the hall, and the "X client" to be the machine on their desk.

X client::
Each X application, such as XTerm or Firefox, is a "client".
A client sends messages to the server such as "Please draw a window at these coordinates", and the server sends back messages such as "The user just clicked on the OK button".
+
In a home or small office environment, the X server and the X clients commonly run on the same computer.
It is also possible to run the X server on a less powerful computer and to run the X applications on a more powerful system.
In this scenario, the communication between the X client and server takes place over the network.

window manager::
X does not dictate what windows should look like on-screen, how to move them around with the mouse, which keystrokes should be used to move between windows, what the title bars on each window should look like, whether or not they have close buttons on them, and so on.
Instead, X delegates this responsibility to a separate window manager application.
There are http://www.xwinman.org/[dozens of window managers] available.
Each window manager provides a different look and feel: some support virtual desktops, some allow customized keystrokes to manage the desktop, some have a "Start" button, and some are themeable, allowing a complete change of the desktop's look-and-feel.
Window managers are available in the [.filename]#x11-wm# category of the Ports Collection.
+
Each window manager uses a different configuration mechanism.
Some expect configuration file written by hand while others provide graphical tools for most configuration tasks.

desktop environment::
KDE and GNOME are considered to be desktop environments as they include an entire suite of applications for performing common desktop tasks.
These may include office suites, web browsers, and games.

focus policy::
The window manager is responsible for the mouse focus policy.
This policy provides some means for choosing which window is actively receiving keystrokes and it should also visibly indicate which window is currently active.
+
One focus policy is called "click-to-focus".
In this model, a window becomes active upon receiving a mouse click.
In the "focus-follows-mouse" policy, the window that is under the mouse pointer has focus and the focus is changed by pointing at another window.
If the mouse is over the root window, then this window is focused.
In the "sloppy-focus" model, if the mouse is moved over the root window, the most recently used window still has the focus.
With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window.
In the "click-to-focus" policy, the active window is selected by mouse click.
The window may then be raised and appear in front of all other windows.
All keystrokes will now be directed to this window, even if the cursor is moved to another window.
+
Different window managers support different focus models.
All of them support click-to-focus, and the majority of them also support other policies.
Consult the documentation for the window manager to determine which focus models are available.

widgets::
Widget is a term for all of the items in the user interface that can be clicked or manipulated in some way.
This includes buttons, check boxes, radio buttons, icons, and lists.
A widget toolkit is a set of widgets used to create graphical applications.
There are several popular widget toolkits, including Qt, used by KDE, and GTK+, used by GNOME.
As a result, applications will have a different look and feel, depending upon which widget toolkit was used to create the application.

[[x-install]]
== Installing Xorg

On FreeBSD, Xorg can be installed as a package or port.

The binary package can be installed quickly but with fewer options for customization:

[source,shell]
....
# pkg install xorg
....

To build and install from the Ports Collection:

[source,shell]
....
# cd /usr/ports/x11/xorg
# make install clean
....

Either of these installations results in the complete Xorg system being installed.
Binary packages are the best option for most users.

A smaller version of the X system suitable for experienced users is available in package:x11/xorg-minimal[].
Most of the documents, libraries, and applications will not be installed.
Some applications require these additional components to function.

[[x-config]]
== Xorg Configuration

[[x-config-quick-start]]
=== Quick Start

Xorg supports most common video cards, keyboards, and pointing devices.

[TIP]
====
Video cards, monitors, and input devices are automatically detected and do not require any manual configuration.
Do not create [.filename]#xorg.conf# or run a `-configure` step unless automatic configuration fails.
====

[.procedure]
. If Xorg has been used on this computer before, move or remove any existing configuration files:
+
[source,shell]
....
# 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:
+
[source,shell]
....
# pw groupmod video -m jru || pw groupmod wheel -m jru
....

. The `TWM` window manager is included by default. It is started when Xorg starts:
+
[source,shell]
....
% startx
....

. On some older versions of FreeBSD, the system console must be set to man:vt[4] before switching back to the text console will work properly. See <<x-config-kms>>.

[[x-config-user-group]]
=== User Group for Accelerated Video

Access to [.filename]#/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, man:pw[8] is used to add user _slurms_ to the `video` group, or to the `wheel` group if there is no `video` group:

[source,shell]
....
# pw groupmod video -m slurms || pw groupmod wheel -m slurms
....

[[x-config-kms]]
=== Kernel Mode Setting (`KMS`)

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 man: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 man:vt[4] console avoids this problem.

Add this line to [.filename]#/boot/loader.conf# to enable man:vt[4]:

[.programlisting]
....
kern.vty=vt
....

[[x-config-files]]
=== Configuration Files

Manual configuration is usually not necessary.
Please do not manually create configuration files unless autoconfiguration does not work.

[[x-config-files-directory]]
==== Directory

Xorg looks in several directories for configuration files.
[.filename]#/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 [.filename]#/etc/X11/# still works.
However, this mixes application files with the base FreeBSD files and is not recommended.

[[x-config-files-single-or-multi]]
==== Single or Multiple Files

It is easier to use multiple files that each configure a specific setting than the traditional single [.filename]#xorg.conf#.
These files are stored in the [.filename]#xorg.conf.d/# subdirectory of the main configuration file directory.
The full path is typically [.filename]#/usr/local/etc/X11/xorg.conf.d/#.

Examples of these files are shown later in this section.

The traditional single [.filename]#xorg.conf# still works, but is neither as clear nor as flexible as multiple files in the [.filename]#xorg.conf.d/# subdirectory.

[[x-config-video-cards]]
=== Video Cards

The Ports framework provides the drm graphics drivers necessary for X11 operation on recent hardware.
Users can use one of the following drivers available from package:graphics/drm-kmod[].
These drivers use interfaces in the kernel that are normally private.
As such, it is strongly recommended that the drivers be built via the ports system via the `PORTS_MODULES` variable.
With `PORTS_MODULES`, every time you build the kernel, the corresponding port(s) containing kernel modules are re-built against the updated sources.
This ensures the kernel module stays in-sync with the kernel itself.
The kernel and ports trees should be updated together for maximum compatibility.
You can add `PORTS_MODULES` to your [.filename]#/etc/make.conf# file to ensure all kernels you build rebuild this module.
Advanced users can add it to their kernel config files with the `makeoptions` directive.
If you run GENERIC and use freebsd-update, you can just build the [.filename]#graphics/drm-kmod# or [.filename]#x11/nvidia-driver# port after each `freebsd-update install` invocation.

[example]
====
[.filename]#/etc/make.conf#

[.programlisting]
....
SYSDIR=path/to/src/sys
PORTS_MODULES=graphics/drm-kmod x11/nvidia-driver
....
This will rebuild everything, but can select one or the other depending on which GPU / graphics card you have.
====

[[x-config-video-cards-ports]]
Intel KMS driver, Radeon KMS driver, AMD KMS driver::
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.

[[x-config-video-cards-intel]]
Intel(R)::
3D acceleration is supported on most Intel(R) 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[].

[[x-config-video-cards-radeon]]
AMD(R) Radeon::
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[].

[[x-config-video-cards-nvidia]]
NVIDIA::
Several NVIDIA drivers are available in the [.filename]#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[].
+
Kernel support for NVIDIA cards is found in either the [.filename]#x11/nvidia-driver# port or the [.filename]#x11/nvidia-driver-xxx# port.
Modern cards use the former.
Legacy cards use the -xxx ports, where xxx is one of 304, 340 or 390 indicating the version of the driver.
For those, fill in the `-xxx` using the http://download.nvidia.com/XFree86/FreeBSD-x86_64/465.19.01/README/[ Supported NVIDIA GPU Products ] page.
This page lists the devices supported by different versions of the driver.
Legacy drivers run on both i386 and amd64.
The current driver only supports amd64.
Read http://download.nvidia.com/XFree86/FreeBSD-x86_64/465.19.01/README/[installation and configuration of NVIDIA driver] for details.
While we recommend this driver be rebuilt with each kernel rebuild for maximum safety, it uses almost no private kernel interfaces and is usually safe across kernel updates.

[[x-config-video-cards-hybrid]]
Hybrid Combination Graphics::
Some notebook computers add additional graphics processing units to those built into the chipset or processor.
_Optimus_ combines Intel(R) and NVIDIA hardware.
_Switchable Graphics_ or _Hybrid Graphics_ are a combination of an Intel(R) or AMD(R) processor and an AMD(R) 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(R) video can then be used with an Intel(R) driver.
+
`BIOS` settings depend on the model of computer.
In some situations, both ``GPU``s 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.

[[x-config-video-cards-other]]
Other Video Cards::
Drivers for some less-common video cards can be found in the [.filename]#x11-drivers# directory of the Ports Collection.
+
Cards that are not supported by a specific driver might still be usable with the package:x11-drivers/xf86-video-vesa[] driver.
This driver is installed by package:x11/xorg[].
It can also be installed manually as package:x11-drivers/xf86-video-vesa[].
Xorg attempts to use this driver when a specific driver is not found for the video card.
+
package:x11-drivers/xf86-video-scfb[] is a similar nonspecialized video driver that works on many `UEFI` and ARM(R) computers.

[[x-config-video-cards-file]]
Setting the Video Driver in a File::
To set the Intel(R) driver in a configuration file:
+
[[x-config-video-cards-file-intel]]
.Select Intel(R) Video Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/driver-intel.conf#

[.programlisting]
....
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 ``ID``s can be displayed with `pciconf -lv | grep -B3 display`.
====
+
To set the Radeon driver in a configuration file:
+
[[x-config-video-cards-file-radeon]]
.Select Radeon Video Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/driver-radeon.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "radeon"
EndSection
....

====
+
To set the `VESA` driver in a configuration file:
+
[[x-config-video-cards-file-vesa]]
.Select `VESA` Video Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/driver-vesa.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "vesa"
EndSection
....

====
+
To set the `scfb` driver for use with a `UEFI` or ARM(R) computer:
+
[[x-config-video-cards-file-scfb]]
.Select `scfb` Video Driver in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/driver-scfb.conf#

[.programlisting]
....
Section "Device"
	Identifier "Card0"
	Driver     "scfb"
EndSection
....
====

[[x-config-monitors]]
=== Monitors

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 man:xrandr[1].

[[x-config-monitors-xrandr]]
Using man:xrandr[1]::
Run man:xrandr[1] without any parameters to see a list of video outputs and detected monitor modes:
+
[source,shell]
....
% xrandr
Screen 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 man:xrandr[1].
For example, to switch to 1280x1024 at 60 Hz:
+
[source,shell]
....
% xrandr --output DVI-0 --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 man:xrandr[1] to list all the available outputs:
+
[source,shell]
....
% xrandr
Screen 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.
man: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:
+
[source,shell]
....
% 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`.
+
man:xrandr[1] is often run from [.filename]#.xinitrc# to set the appropriate mode when X starts.

[[x-config-monitors-files]]
Setting Monitor Resolution in a File::
To set a screen resolution of 1024x768 in a configuration file:
+
.Set Screen Resolution in a File
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/screen-resolution.conf#

[.programlisting]
....
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.
+
.Manually Setting Monitor Frequencies
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf#

[.programlisting]
....
Section "Monitor"
	Identifier   "Monitor0"
	HorizSync    30-83   # kHz
	VertRefresh  50-76   # Hz
EndSection
....

====

[[x-config-input]]
=== Input Devices

[[x-config-input-keyboard]]
==== Keyboards

[[x-config-input-keyboard-layout]]
Keyboard Layout::
The standardized location of keys on a keyboard is called a _layout_.
Layouts and other adjustable parameters are listed in man: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.
+
.Setting a Keyboard Layout
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/keyboard-fr.conf#

[.programlisting]
....
Section	"InputClass"
	Identifier	"KeyboardDefaults"
	MatchIsKeyboard	"on"
	Option		"XkbLayout" "fr"
EndSection
....

====
+
.Setting Multiple Keyboard Layouts
[example]
====
Set United States, Spanish, and Ukrainian keyboard layouts.
Cycle through these layouts by pressing kbd:[Alt+Shift].
package:x11/xxkb[] or package:x11/sbxkb[] can be used for improved layout switching control and current layout indicators.

[.filename]#/usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf#

[.programlisting]
....
Section	"InputClass"
	Identifier	"All Keyboards"
	MatchIsKeyboard	"yes"
	Option		"XkbLayout" "us, es, ua"
EndSection
....

====

[[x-config-input-keyboard-zap]]
Closing Xorg From the Keyboard::
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:
+
.Enabling Keyboard Exit from X
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf#

[.programlisting]
....
Section	"InputClass"
	Identifier	"KeyboardDefaults"
	MatchIsKeyboard	"on"
	Option		"XkbOptions" "terminate:ctrl_alt_bksp"
EndSection
....

====

[[x11-input-mice]]
==== Mice and Pointing Devices

[IMPORTANT]
====
If using package:xorg-server[] 1.20.8 or later under FreeBSD {rel121-current} and not using man:moused[8], add `kern.evdev.rcpt_mask=12` to [.filename]#/etc/sysctl.conf#.
====

Many mouse parameters can be adjusted with configuration options.
See man:mousedrv[4] for a full list.
[[x11-input-mice-buttons]]
Mouse Buttons::
The number of buttons on a mouse can be set in the mouse `InputDevice` section of [.filename]#xorg.conf#.
To set the number of buttons to 7:
+
.Setting the Number of Mouse Buttons
[example]
====
[.filename]#/usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf#

[.programlisting]
....
Section "InputDevice"
	Identifier  "Mouse0"
	Option      "Buttons" "7"
EndSection
....

====

[[x-config-manual-configuration]]
=== Manual Configuration

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.

[WARNING]
====
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 [.filename]#xorg.conf#:

[source,shell]
....
# Xorg -configure
....

The configuration file is saved to [.filename]#/root/xorg.conf.new#.
Make any changes desired, then test that file (using `-retro` so there is a visible background) with:

[source,shell]
....
# Xorg -retro -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, [.filename]#/usr/local/etc/X11/xorg.conf.d/#.

[[x-fonts]]
== Using Fonts in Xorg

[[type1]]
=== Type1 Fonts

The default fonts that ship with Xorg are less than ideal for typical desktop publishing applications.
Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible.
However, there are several free, high quality Type1 (PostScript(R)) fonts available which can be readily used with Xorg.
For instance, the URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others).
The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts.
In addition, Xorg can be configured to use TrueType(R) fonts with a minimum of effort.
For more details on this, see the man:X[7] manual page or <<truetype>>.

To install the above Type1 font collections from binary packages, run the following commands:

[source,shell]
....
# pkg install urwfonts
....

Alternatively, to build from the Ports Collection, run the following commands:

[source,shell]
....
# cd /usr/ports/x11-fonts/urwfonts
# make install clean
....

And likewise with the freefont or other collections.
To have the X server detect these fonts, add an appropriate line to the X server configuration file ([.filename]#/etc/X11/xorg.conf#), which reads:

[.programlisting]
....
FontPath "/usr/local/share/fonts/urwfonts/"
....

Alternatively, at the command line in the X session run:

[source,shell]
....
% xset fp+ /usr/local/share/fonts/urwfonts
% xset fp rehash
....

This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM).
A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as demonstrated in <<antialias>>.

[[truetype]]
=== TrueType(R) Fonts

Xorg has built in support for rendering TrueType(R) fonts.
There are two different modules that can enable this functionality.
The freetype module is used in this example because it is more consistent with the other font rendering back-ends.
To enable the freetype module just add the following line to the `"Module"` section of [.filename]#/etc/X11/xorg.conf#.

[.programlisting]
....
Load  "freetype"
....

Now make a directory for the TrueType(R) fonts (for example, [.filename]#/usr/local/share/fonts/TrueType#) and copy all of the TrueType(R) fonts into this directory.
Keep in mind that TrueType(R) fonts cannot be directly taken from an Apple(R) Mac(R); they must be in UNIX(R)/MS-DOS(R)/Windows(R) format for use by Xorg.
Once the files have been copied into this directory, use mkfontscale to create a [.filename]#fonts.dir#, so that the X font renderer knows that these new files have been installed.
`mkfontscale` can be installed as a package:

[source,shell]
....
# pkg install mkfontscale
....

Then create an index of X font files in a directory:

[source,shell]
....
# cd /usr/local/share/fonts/TrueType
# mkfontscale
....

Now add the TrueType(R) directory to the font path.
This is just the same as described in <<type1>>:

[source,shell]
....
% xset fp+ /usr/local/share/fonts/TrueType
% xset fp rehash
....

or add a `FontPath` line to [.filename]#xorg.conf#.

Now Gimp, LibreOffice, and all of the other X applications should now recognize the installed TrueType(R) fonts.
Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within LibreOffice) will look much better now.

[[antialias]]
=== Anti-Aliased Fonts

All fonts in Xorg that are found in [.filename]#/usr/local/share/fonts/# and [.filename]#~/.fonts/# are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox.

To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file [.filename]#/usr/local/etc/fonts/local.conf#.
Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities.
For more details, please see man:fonts-conf[5].

This file must be in XML format.
Pay careful attention to case, and make sure all tags are properly closed.
The file begins with the usual XML header followed by a DOCTYPE definition, and then the `<fontconfig>` tag:

[.programlisting]
....
<?xml version="1.0"?>
      <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
      <fontconfig>
....

As previously stated, all fonts in [.filename]#/usr/local/share/fonts/# as well as [.filename]#~/.fonts/# are already made available to Xft-aware applications.
To add another directory outside of these two directory trees, add a line like this to [.filename]#/usr/local/etc/fonts/local.conf#:

[.programlisting]
....
<dir>/path/to/my/fonts</dir>
....

After adding new fonts, and especially new font directories, rebuild the font caches:

[source,shell]
....
# fc-cache -f
....

Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes "staircases" from large text, but can cause eyestrain if applied to normal text.
To exclude font sizes smaller than 14 point from anti-aliasing, include these lines:

[.programlisting]
....
        <match target="font">
	    <test name="size" compare="less">
		<double>14</double>
	    </test>
	    <edit name="antialias" mode="assign">
		<bool>false</bool>
	    </edit>
	</match>
	<match target="font">
	    <test name="pixelsize" compare="less" qual="any">
		<double>14</double>
	    </test>
	    <edit mode="assign" name="antialias">
		<bool>false</bool>
	    </edit>
	</match>
....

Spacing for some monospaced fonts might also be inappropriate with anti-aliasing.
This seems to be an issue with KDE, in particular.
One possible fix is to force the spacing for such fonts to be 100.
Add these lines:

[.programlisting]
....
	<match target="pattern" name="family">
	   <test qual="any" name="family">
	       <string>fixed</string>
	   </test>
	   <edit name="family" mode="assign">
	       <string>mono</string>
	   </edit>
	</match>
	<match target="pattern" name="family">
	    <test qual="any" name="family">
		<string>console</string>
	    </test>
	    <edit name="family" mode="assign">
		<string>mono</string>
	    </edit>
	</match>
....

(this aliases the other common names for fixed fonts as `"mono"`), and then add:

[.programlisting]
....
         <match target="pattern" name="family">
	     <test qual="any" name="family">
		 <string>mono</string>
	     </test>
	     <edit name="spacing" mode="assign">
		 <int>100</int>
	     </edit>
	 </match>
....

Certain fonts, such as Helvetica, may have a problem when anti-aliased.
Usually this manifests itself as a font that seems cut in half vertically.
At worst, it may cause applications to crash.
To avoid this, consider adding the following to [.filename]#local.conf#:

[.programlisting]
....
         <match target="pattern" name="family">
	     <test qual="any" name="family">
		 <string>Helvetica</string>
	     </test>
	     <edit name="family" mode="assign">
		 <string>sans-serif</string>
	     </edit>
	 </match>
....

After editing [.filename]#local.conf#, make certain to end the file with the `</fontconfig>` tag.
Not doing this will cause changes to be ignored.

Users can add personalized settings by creating their own [.filename]#~/.config/fontconfig/fonts.conf#.
This file uses the same `XML` format described above.

One last point: with an LCD screen, sub-pixel sampling may be desired.
This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic.
To enable this, add the line somewhere in [.filename]#local.conf#:

[.programlisting]
....
	 <match target="font">
	     <test qual="all" name="rgba">
		 <const>unknown</const>
	     </test>
	     <edit name="rgba" mode="assign">
		 <const>rgb</const>
	     </edit>
	 </match>
....

[NOTE]
====
Depending on the sort of display, `rgb` may need to be changed to `bgr`, `vrgb` or `vbgr`: experiment and see which works best.
====

[[x-xdm]]
== The X Display Manager

Xorg provides an X Display Manager, XDM, which can be used for login session management.
XDM provides a graphical interface for choosing which display server to connect to and for entering authorization information such as a login and password combination.

This section demonstrates how to configure the X Display Manager on FreeBSD.
Some desktop environments provide their own graphical login manager.
Refer to <<x11-wm-gnome>> for instructions on how to configure the GNOME Display Manager and <<x11-wm-kde>> for instructions on how to configure the KDE Display Manager.

=== Configuring XDM

To install XDM, use the package:x11/xdm[] package or port.
Once installed, XDM can be configured to run when the machine boots up by adding the following line to [.filename]#/etc/rc.conf#:

[.programlisting]
....
xdm_enable="YES"
....

XDM will run on the ninth virtual terminal by default.

The XDM configuration directory is located in [.filename]#/usr/local/etc/X11/xdm#.
This directory contains several files used to change the behavior and appearance of XDM, as well as a few scripts and programs used to set up the desktop when XDM is running.
<<xdm-config-files>> summarizes the function of each of these files.
The exact syntax and usage of these files is described in man:xdm[8].

[[xdm-config-files]]
.XDM Configuration Files
[cols="1,1", frame="none", options="header"]
|===
| File
| Description

|[.filename]#Xaccess#
|The protocol for connecting to XDM is called the X Display Manager Connection Protocol (`XDMCP`). This file is a client authorization ruleset for controlling `XDMCP` connections from remote machines. By default, this file does not allow any remote clients to connect.

|[.filename]#Xresources#
|This file controls the look and feel of the XDM display chooser and login screens. The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. The format of this file is identical to the app-defaults file described in the Xorg documentation.

|[.filename]#Xservers#
|The list of local and remote displays the chooser should provide as login choices.

|[.filename]#Xsession#
|Default session script for logins which is run by XDM after a user has logged in. This points to a customized session script in [.filename]#~/.xsession#.

|[.filename]#Xsetup_#*
|Script to automatically launch applications before displaying the chooser or login interfaces. There is a script for each display being used, named [.filename]#Xsetup_*#, where `*` is the local display number. Typically these scripts run one or two programs in the background such as `xconsole`.

|[.filename]#xdm-config#
|Global configuration for all displays running on this machine.

|[.filename]#xdm-errors#
|Contains errors generated by the server program. If a display that XDM is trying to start hangs, look at this file for error messages. These messages are also written to the user's [.filename]#~/.xsession-errors# on a per-session basis.

|[.filename]#xdm-pid#
|The running process `ID` of XDM.
|===

=== Configuring Remote Access

By default, only users on the same system can login using XDM.
To enable users on other systems to connect to the display server, edit the access control rules and enable the connection listener.

To configure XDM to listen for any remote connection, comment out the `DisplayManager.requestPort` line in [.filename]#/usr/local/etc/X11/xdm/xdm-config# by putting a `!` in front of it:

[source,shell]
....
! SECURITY: do not listen for XDMCP or Chooser requests
! Comment out this line if you want to manage X terminals with xdm
DisplayManager.requestPort:     0
....

Save the edits and restart XDM.
To restrict remote access, look at the example entries in [.filename]#/usr/local/etc/X11/xdm/Xaccess# and refer to man:xdm[8] for further information.

[[x11-wm]]
== Desktop Environments

This section describes how to install three popular desktop environments on a FreeBSD system.
A desktop environment can range from a simple window manager to a complete suite of desktop applications.
Over a hundred desktop environments are available in the [.filename]#x11-wm# category of the Ports Collection.

[[x11-wm-gnome]]
=== GNOME

GNOME is a user-friendly desktop environment.
It includes a panel for starting applications and displaying status, a desktop, a set of tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other.
More information regarding GNOME on FreeBSD can be found at https://www.FreeBSD.org/gnome[https://www.FreeBSD.org/gnome].
That web site contains additional documentation about installing, configuring, and managing GNOME on FreeBSD.

This desktop environment can be installed from a package:

[source,shell]
....
# pkg install gnome
....

To instead build GNOME from ports, use the following command.
GNOME is a large application and will take some time to compile, even on a fast computer.

[source,shell]
....
# cd /usr/ports/x11/gnome
# make install clean
....

GNOME requires [.filename]#/proc# to be mounted.
Add this line to [.filename]#/etc/fstab# to mount this file system automatically during system startup:

[.programlisting]
....
proc           /proc       procfs  rw  0   0
....

GNOME uses D-Bus for a message bus and hardware abstraction.
These applications are automatically installed as dependencies of GNOME.
Enable them in [.filename]#/etc/rc.conf# so they will be started when the system boots:

[.programlisting]
....
dbus_enable="YES"
....

After installation, configure Xorg to start GNOME.
The easiest way to do this is to enable the GNOME Display Manager, GDM, which is installed as part of the GNOME package or port.
It can be enabled by adding this line to [.filename]#/etc/rc.conf#:

[.programlisting]
....
gdm_enable="YES"
....

It is often desirable to also start all GNOME services.
To achieve this, add a second line to [.filename]#/etc/rc.conf#:

[.programlisting]
....
gnome_enable="YES"
....

GDM will start automatically when the system boots.

A second method for starting GNOME is to type `startx` from the command-line after configuring [.filename]#~/.xinitrc#.
If this file already exists, replace the line that starts the current window manager with one that starts [.filename]#/usr/local/bin/gnome-session#.
If this file does not exist, create it with this command:

[source,shell]
....
% echo "exec /usr/local/bin/gnome-session" > ~/.xinitrc
....

A third method is to use XDM as the display manager.
In this case, create an executable [.filename]#~/.xsession#:

[source,shell]
....
% echo "exec /usr/local/bin/gnome-session" > ~/.xsession
....

[[x11-wm-kde]]
=== KDE

KDE is another easy-to-use desktop environment.
This desktop provides a suite of applications with a consistent look and feel, a standardized menu and toolbars, keybindings, color-schemes, internationalization, and a centralized, dialog-driven desktop configuration.
More information on KDE can be found at http://www.kde.org/[http://www.kde.org/].
For FreeBSD-specific information, consult http://freebsd.kde.org/[http://freebsd.kde.org].

To install the KDE package, type:

[source,shell]
....
# pkg install x11/kde5
....

To instead build the KDE port, use the following command.
Installing the port will provide a menu for selecting which components to install.
KDE is a large application and will take some time to compile, even on a fast computer.

[source,shell]
....
# cd /usr/ports/x11/kde5
# make install clean
....

KDE requires [.filename]#/proc# to be mounted.
Add this line to [.filename]#/etc/fstab# to mount this file system automatically during system startup:

[.programlisting]
....
proc           /proc       procfs  rw  0   0
....

KDE uses D-Bus for a message bus and hardware abstraction.
These applications are automatically installed as dependencies of KDE.
Enable them in [.filename]#/etc/rc.conf# so they will be started when the system boots:

[.programlisting]
....
dbus_enable="YES"
....

Since KDE Plasma 5, the KDE Display Manager, KDM is no longer developed.
A possible replacement is SDDM.
To install it, type:

[source,shell]
....
# pkg install x11/sddm
....

Add this line to [.filename]#/etc/rc.conf#:

[.programlisting]
....
sddm_enable="YES"
....

A second method for launching KDE Plasma is to type `startx` from the command line.
For this to work, the following line is needed in [.filename]#~/.xinitrc#:

[.programlisting]
....
exec ck-launch-session startplasma-x11
....

A third method for starting KDE Plasma is through XDM.
To do so, create an executable [.filename]#~/.xsession# as follows:

[source,shell]
....
% echo "exec ck-launch-session startplasma-x11" > ~/.xsession
....

Once KDE Plasma is started, refer to its built-in help system for more information on how to use its various menus and applications.

[[x11-wm-xfce]]
=== Xfce

Xfce is a desktop environment based on the GTK+ toolkit used by GNOME.
However, it is more lightweight and provides a simple, efficient, easy-to-use desktop.
It is fully configurable, has a main panel with menus, applets, and application launchers, provides a file manager and sound manager, and is themeable.
Since it is fast, light, and efficient, it is ideal for older or slower machines with memory limitations.
More information on Xfce can be found at http://www.xfce.org/[http://www.xfce.org].

To install the Xfce package:

[source,shell]
....
# pkg install xfce
....

Alternatively, to build the port:

[source,shell]
....
# cd /usr/ports/x11-wm/xfce4
# make install clean
....

Xfce uses D-Bus for a message bus.
This application is automatically installed as dependency of Xfce.
Enable it in [.filename]#/etc/rc.conf# so it will be started when the system boots:

[.programlisting]
....
dbus_enable="YES"
....

Unlike GNOME or KDE, Xfce does not provide its own login manager.
In order to start Xfce from the command line by typing `startx`, first create [.filename]#~/.xinitrc# with this command:

[source,shell]
....
% echo ". /usr/local/etc/xdg/xfce4/xinitrc" > ~/.xinitrc
....

An alternate method is to use XDM.
To configure this method, create an executable [.filename]#~/.xsession#:

[source,shell]
....
% echo ". /usr/local/etc/xdg/xfce4/xinitrc" > ~/.xsession
....

[[x-compiz-fusion]]
== Installing Compiz Fusion

One way to make using a desktop computer more pleasant is with nice 3D effects.

Installing the Compiz Fusion package is easy, but configuring it requires a few steps that are not described in the port's documentation.

[[x-compiz-video-card]]
=== Setting up the FreeBSD nVidia Driver

Desktop effects can cause quite a load on the graphics card.
For an nVidia-based graphics card, the proprietary driver is required for good performance.
Users of other graphics cards can skip this section and continue with the [.filename]#xorg.conf# configuration.

To determine which nVidia driver is needed see the extref:{faq}[FAQ question on the subject, idp59950544].

Having determined the correct driver to use for your card, installation is as simple as installing any other package.

For example, to install the latest driver:

[source,shell]
....
# pkg install x11/nvidia-driver
....

The driver will create a kernel module, which needs to be loaded at system startup.
Use man:sysrc[8] to load the module at startup:

[source,shell]
....
# sysrc kld_list+="nvidia"
....

Alternatively, add the following line to [.filename]#/boot/loader.conf#:

[.programlisting]
....
nvidia_load="YES"
....

[NOTE]
====
To immediately load the kernel module into the running kernel issue a command like `kldload nvidia`.
However, it has been noted that some versions of Xorg will not function properly if the driver is not loaded at boot time.
After editing [.filename]#/boot/loader.conf#, a reboot is recommended.
Improper settings in [.filename]#/boot/loader.conf# can cause the system not to boot properly.
====

With the kernel module loaded, you normally only need to change a single line in [.filename]#xorg.conf# to enable the proprietary driver:

Find the following line in [.filename]#/etc/X11/xorg.conf#:

[.programlisting]
....
Driver      "nv"
....

and change it to:

[.programlisting]
....
Driver      "nvidia"
....

Start the GUI as usual, and you should be greeted by the nVidia splash.
Everything should work as usual.

[[xorg-configuration]]
=== Configuring `xorg.conf` for Desktop Effects

To enable Compiz Fusion, [.filename]#/etc/X11/xorg.conf# needs to be modified:

Add the following section to enable composite effects:

[.programlisting]
....
Section "Extensions"
    Option         "Composite" "Enable"
EndSection
....

Locate the "Screen" section which should look similar to the one below:

[.programlisting]
....
Section "Screen"
    Identifier     "Screen0"
    Device         "Card0"
    Monitor        "Monitor0"
    ...
....

and add the following two lines (after "Monitor" will do):

[.programlisting]
....
DefaultDepth    24
Option         "AddARGBGLXVisuals" "True"
....

Locate the "Subsection" that refers to the screen resolution that you wish to use.
For example, if you wish to use 1280x1024, locate the section that follows.
If the desired resolution does not appear in any subsection, you may add the relevant entry by hand:

[.programlisting]
....
SubSection     "Display"
    Viewport    0 0
    Modes      "1280x1024"
EndSubSection
....

A color depth of 24 bits is needed for desktop composition, change the above subsection to:

[.programlisting]
....
SubSection     "Display"
    Viewport    0 0
    Depth       24
    Modes      "1280x1024"
EndSubSection
....

Finally, confirm that the "glx" and "extmod" modules are loaded in the "Module" section:

[.programlisting]
....
Section "Module"
    Load           "extmod"
    Load           "glx"
    ...
....

The preceding can be done automatically with package:x11/nvidia-xconfig[] by running (as root):

[source,shell]
....
# nvidia-xconfig --add-argb-glx-visuals
# nvidia-xconfig --composite
# nvidia-xconfig --depth=24
....

[[compiz-fusion]]
=== Installing and Configuring Compiz Fusion

Installing Compiz Fusion is as simple as any other package:

[source,shell]
....
# pkg install x11-wm/compiz-fusion
....

When the installation is finished, start your graphic desktop and at a terminal, enter the following commands (as a normal user):

[source,shell]
....
% compiz --replace --sm-disable --ignore-desktop-hints ccp &
% emerald --replace &
....

Your screen will flicker for a few seconds, as your window manager (e.g., Metacity if you are using GNOME) is replaced by Compiz Fusion.
Emerald takes care of the window decorations (i.e., close, minimize, maximize buttons, title bars and so on).

You may convert this to a trivial script and have it run at startup automatically (e.g., by adding to "Sessions" in a GNOME desktop):

[.programlisting]
....
#! /bin/sh
compiz --replace --sm-disable --ignore-desktop-hints ccp &
emerald --replace &
....

Save this in your home directory as, for example, [.filename]#start-compiz# and make it executable:

[source,shell]
....
% chmod +x ~/start-compiz
....

Then use the GUI to add it to [.guimenuitem]#Startup Programs# (located in [.guimenuitem]#System#, [.guimenuitem]#Preferences#, [.guimenuitem]#Sessions# on a GNOME desktop).

To actually select all the desired effects and their settings, execute (again as a normal user) the Compiz Config Settings Manager:

[source,shell]
....
% ccsm
....

[NOTE]
====
In GNOME, this can also be found in the [.guimenuitem]#System#, [.guimenuitem]#Preferences# menu.
====

If you have selected "gconf support" during the build, you will also be able to view these settings using `gconf-editor` under `apps/compiz`.

[[x11-troubleshooting]]
== Troubleshooting

If the mouse does not work, you will need to first configure it before proceeding.
In recent Xorg versions, the `InputDevice` sections in [.filename]#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:

[.programlisting]
....
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]
====
[WARNING]
=====
This section contains partially outdated information.
The HAL daemon (hald) is no longer a part of the FreeBSD desktop setup.
=====
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 man: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 [.filename]#x11-input.fdi# and saved in the [.filename]#/usr/local/etc/hal/fdi/policy# directory.
This file should contain the following lines:

[.programlisting]
....
<?xml version="1.0" encoding="utf-8"?>
<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:

[source,shell]
....
% setxkbmap -model pc102 -layout fr
....

[.filename]#/usr/local/share/X11/xkb/rules/base.lst# lists the various keyboard, layouts and options available.
====

The [.filename]#xorg.conf.new# configuration file may now be tuned to taste.
Open the file in a text editor such as man:emacs[1] or man: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 [.filename]#xorg.conf.new# under the `"Monitor"` section:

[.programlisting]
....
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 man: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:

[.programlisting]
....
Option       "DPMS"
....

While the [.filename]#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:

[.programlisting]
....
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 man: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 Xorg log files, which contain information on each device that the Xorg server attaches to.
Xorg log file names are in the format of [.filename]#/var/log/Xorg.0.log#.
The exact name of the log can vary from [.filename]#Xorg.0.log# to [.filename]#Xorg.8.log# and so forth.
====

If all is well, the configuration file needs to be installed in a common location where man:Xorg[1] can find it.
This is typically [.filename]#/etc/X11/xorg.conf# or [.filename]#/usr/local/etc/X11/xorg.conf#.

[source,shell]
....
# cp xorg.conf.new /etc/X11/xorg.conf
....

The Xorg configuration process is now complete.
Xorg may be now started with the man:startx[1] utility.
The Xorg server may also be started with the use of man:xdm[8].

=== Configuration with Intel(R) `i810` Graphics Chipsets

Configuration with Intel(R) i810 integrated chipsets requires the [.filename]#agpgart# AGP programming interface for Xorg to drive the card.
See the man: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 man:agp[4] driver compiled in the kernel, trying to load the module with man:kldload[8] will not work.
This driver has to be in the kernel at boot time through being compiled in or using [.filename]#/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:

[.programlisting]
....
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 [.filename]#/var/log/Xorg.0.log# one can extract enough information to manually create a `ModeLine` that will work.
Simply look for information resembling this:

[.programlisting]
....
(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:

[.programlisting]
....
ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings>
....

So that the `ModeLine` in `Section "Monitor"` for this example would look like this:

[.programlisting]
....
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.

[[compiz-troubleshooting]]
=== Troubleshooting Compiz Fusion

==== I have installed Compiz Fusion, and after running the commands you mention, my windows are left without title bars and buttons. What is wrong?

You are probably missing a setting in [.filename]#/etc/X11/xorg.conf#.
Review this file carefully and check especially the `DefaultDepth` and `AddARGBGLXVisuals` directives.

==== When I run the command to start Compiz Fusion, the X server crashes and I am back at the console. What is wrong?

If you check [.filename]#/var/log/Xorg.0.log#, you will probably find error messages during the X startup.
The most common would be:

[source,shell]
....
(EE) NVIDIA(0):     Failed to initialize the GLX module; please check in your X
(EE) NVIDIA(0):     log file that the GLX module has been loaded in your X
(EE) NVIDIA(0):     server, and that the module is the NVIDIA GLX module.  If
(EE) NVIDIA(0):     you continue to encounter problems, Please try
(EE) NVIDIA(0):     reinstalling the NVIDIA driver.
....

This is usually the case when you upgrade Xorg.
You will need to reinstall the package:x11/nvidia-driver[] package so glx is built again.

[[x-wayland]]
== Wayland on FreeBSD
Wayland is a new software for supporting graphical user interfaces, but it differs from Xorg in several important ways.
First, Wayland is only a protocol that acts as an intermediary between clients using a different mechanism which removes the dependency on an X server.
Xorg includes both the X11 protocol, used to run remote displays and the X server will accept connections and display windows.
Under Wayland, the compositor or window manager provides the display server instead of a traditional X server.

Since Wayland is not an X server, traditional X screen connections will need to utilize other methods such as VNC or RDP for remote desktop management. Second, Wayland can manage composite communications between clients and a compositor as a separate entity which does not need to support the X protocols.

Wayland is relatively new, and not all software has been updated to run natively without `Xwayland` support.
Because Wayland does not provide the X server, and expects compositors to provide that support, X11 window managers that do not yet support Wayland will require that `Xwayland` is not started with the `-rootless` parameter.
The `-rootless` parameter, when removed, will restore X11 window manager support.

[NOTE]
====
The current NVidia driver should work with most wl-roots compositors, but it may be a little unstable and not support all features at this time.
Volunteers to help work on the NVidia DRM are requested.
====

Currently, a lot of software will function with minimal issues on Wayland, including Firefox.
And a few desktops are also available, such as the Compiz Fusion replacement, known as Wayfire, and the i3 window manager replacement, Sway.

[NOTE]
====
As of May, 2021, plasma5-kwin does support Wayland on FreeBSD.
To use Plasma under Wayland, use the `startplasma-wayland` parameter to `ck-launch-session` and tie in dbus with:
`ck-launch-session dbus-run-session startplasma-wayland`
to get it working.
====

For compositors, a kernel supporting the man:evdev[4] driver must exist to utilize the keybinding functionality.
This is built into the [.filename]#GENERIC# kernel by default; however, if it has been customized and man:evdev[4] support was stripped out, the man:evdev[4] module will need to be loaded.
In addition, users of `Wayland` will need to be members of the `video` group.
To quickly make this change, use the `pw` command:

[source,shell]
----
pw groupmod video -m user
----

Installing Wayland is simple; there is not a great deal of configuration for the protocol itself.
Most of the composition will depend on the chosen compositor.
By installing `seatd` now, a step is skipped as part of the compositor installation and configuration as `seatd` is needed to provide non-root access to certain devices.
All of the compositors described here should work with package:graphics/drm-kmod[] open source drivers; however, the NVidia graphics cards may have issues when using the proprietary drivers.
Begin by installing the following packages:

[source,shell]
----
# pkg install wayland seatd
----

Once the protocol and supporting packages have been installed, a compositor must create the user interface.
Several compositors will be covered in the following sections.
All compositors using Wayland will need a runtime directory defined in the environment, which can be achieved with the following command in the bourne shell:

[source,shell]
----
% export XDG_RUNTIME_DIR=/var/run/user/`id -u`
----

It is important to note that most compositors will search the XDG_RUNTIME_DIR directory for the configuration files.
In the examples included here, a parameter will be used to specify a configuration file in [.filename]#~/.config# to keep temporary files and configuration files separate.
It is recommended that an alias be configured for each compositor to load the designated configuration file.

[WARNING]
====
It has been reported that ZFS users may experience issues with some Wayland clients because they need access to `posix_fallocate()` in the runtime directory.
While the author could not reproduce this issue on their ZFS system, a recommended workaround is not to use ZFS for the runtime directory and instead use `tmpfs` for the [.filename]#/var/run# directory.
In this case, the `tmpfs` file system is used for [.filename]#/var/run# and mounted through the command `mount -t tmpfs tmpfs /var/run` command and then make this change persist across reboots through [.filename]#/etc/fstab#.
The XDG_RUNTIME_DIR environment variable could be configured to use [.filename]#/var/run/user/$UID# and avoid potential pitfalls with ZFS.
Consider that scenario when reviewing the configuration examples in the following sections.
====

The seatd daemon helps manage access to shared system devices for non-root users in compositors; this includes graphics cards.
For traditional X11 managers, `seatd` is not needed, such as both Plasma and GNOME, but for the Wayland compositors discussed here, it will need enabled on the system and be running before starting a compositor environment.
To enable and start the `seatd` daemon now, and on system initialization:

[source,shell]
----
# sysrc seatd_enable="YES"
# service seatd start
----

Afterward, a compositor, which is similar to an X11 desktop, will need to be installed for the GUI environment.
Three are discussed here, including basic configuration options, setting up a screen lock, and recommendations for more information.

=== The Wayfire Compositor

Wayfire is a compositor that aims to be lightweight and customizable.
Several features are available, and it brings back several elements from the previously released Compiz Fusion desktop.
All of the parts look beautiful on modern hardware. To get Wayfire up and running, begin by installing the required packages:

[source,shell]
----
# pkg install wayfire wf-shell alacritty swaylock-effects swayidle wlogout kanshi mako wlsunset
----

The `alacritty` package provides a terminal emulator.
Still, it is not completely required as other terminal emulators such as `kitty`, and XFCE-4 `Terminal` have been tested and verified to work under the Wayfire compositor.
Wayfire configuration is relatively simple; it uses a file that should be reviewed for any customizations.
To begin, copy the example file over to the runtime environment configuration directory and then edit the file:

[source,shell]
----
% mkdir ~/.config/wayfire
% cp /usr/local/share/examples/wayfire/wayfire.ini ~/.config/wayfire
----

The defaults for most users should be fine.
Within the configuration file, items like the famous `cube` are pre-configured, and there are instructions to help with the available settings.
A few primary settings of note include:

[.programlisting]
....
[output]
mode = 1920x1080@60000
position = 0,0
transform = normal
scale = 1.000000
....

In this example, from the configuration file, the screen's output should be the listed mode at the listed hertz.
For example, the mode should be set to `widthxheight@refresh_rate`.
The position places the output at a specific pixel location specified.
The default should be fine for most users.
Finally, transform sets a background transform, and scale will scale the output to the specified scale factor.
The defaults for these options are generally acceptable; for more information, see the documentation.

As mentioned, Wayland is new, and not all applications work with the protocol yet.
At this time, `sddm` does not appear to support starting and managing compositors in Wayland.
The `swaylock` utility has been used instead in these examples. The configuration file contains options to run `swayidle` and `swaylock` for idle and locking of the screen.
This option to define the action to take when the system is idle is listed as:

[.programlisting]
....
idle = swaylock
....

And the lock timeout is configured using the following lines:

[.programlisting]
....
[idle]
toggle = <super> KEY_Z
screensaver_timeout = 300
dpms_timeout = 600
....

The first option will lock the screen after 300 seconds, and after another 300, the screen will shut off through the `dpms_timeout` option.

One final thing to note is the <super> key.
Most of the configuration mentions this key, and it is the traditional `Windows` key on the keyboard.
Most keyboards have this super key available; however, it should be remapped within this configuration file if it is not available.
For example, to lock the screen, press and hold the super key, the kbd:[shift] key, and press the kbd:[escape] key. 
nless the mappings have changed, this will execute the swaylock application.
The default configuration for `swaylock` will show a grey screen; however, the application is highly customizable and well documented.
In addition, since the swaylock-effects is the version that was installed, there are several options available such as the blur effect, which can be seen using the following command:

[source,shell]
----
% swaylock --effect-blur 7x5
----

There is also the `--clock` parameter which will display a clock with the date and time on the lock screen.
When package:x11/swaylock-effects[] was installed, a default [.filename]#pam.d# configuration was included.
It provides the default options that should be fine for most users.
More advanced options are available; see the PAM documentation for more information.

At this point, it is time to test Wayfire and see if it can start up on the system.
Just type the following command:

[source,shell]
----
% wayfire -c ~/.config/wayfire/wayfire.ini
----

The compositor should now start and display a background image along with a menu bar at the top of the screen.
Wayfire will attempt to list installed compatible applications for the desktop and present them in this drop-down menu; for example, if the XFCE-4 file manager is installed, it will show up in this drop-down menu.
If a specific application is compatible and valuable enough for a keyboard shortcut, it may be mapped to a keyboard sequence using the [.filename]#wayfire.ini# configuration file.
Wayfire also has a configuration tool named Wayfire Config Manager.
It is located in the drop-down menu bar but may also be started through a terminal by issuing the following command:

[source,shell]
----
% wcm
----

Various Wayfire configuration options, including the composite special effects, maybe enabled, disabled, or configured through this application.
In addition, for a more user-friendly experience, a background manager, panel, and docking application may be enabled in the configuration file:

[.programlisting]
....
panel = wf-panel
dock = wf-dock
background = wf-background
....

[WARNING]
====
Changes made through `wcm` will overwrite custom changes in the [.filename]#wayfire.ini# configuration file.
The [.filename]#wayfire.ini# file is highly recommended to be backed up so any essential changes may be restored.
====

Finally, the default launcher listed in the [.filename]#wayfire.ini# is package:x11/wf-shell[] which may be replaced with other panels if desired by the user.

=== The Hikari Compositor

The Hikari compositor uses several concepts centered around productivity, such as sheets, workspaces, and more.
In that way, it resembles a tiling window manager.
Breaking this down, the compositor starts with a single workspace, which is similar to virtual desktops.
Hikari uses a single workspace or virtual desktop for user interaction. The workspace is made up of several views, which are the working windows in the compositor grouped as either sheets or groups.
Both sheets and groups are made up of a collection of views; again, the windows that are grouped together.
When switching between sheets or groups, the active sheet or group will become known collectively as the workspace.
The manual page will break this down into more information on the functions of each but for this document, just consider a single workspace utilizing a single sheet.
Hikari installation will comprise of a single package, package:x11-wm/hikari[], and a terminal emulator `alacritty`:

[source,shell]
----
# pkg install hikari alacritty
----

[NOTE]
====
Other shells, such as `kitty` or the Plasma `Terminal`, will function under Wayland. Users should experiment with their favorite terminal editor to validate compatibility.
====

Hikari uses a configuration file, [.filename]#hikari.conf#, which could either be placed in the XDG_RUNTIME_DIR or specified on startup using the `-c` parameter.
An autostart configuration file is not required but may make the migration to this compositor a little easier.
Beginning the configuration is to create the Hikari configuration directory and copy over the configuration file for editing:

[source,shell]
----
% mkdir ~/.config/hikari
% cp /usr/local/etc/hikari/hikari.conf ~/.config/hikari
----

The configuration is broken out into various stanzas such as ui, outputs, layouts, and more.
For most users, the defaults will function fine; however, some important changes should be made.
For example, the $TERMINAL variable is normally not set within the user's environment.
Changing this variable or altering the [.filename]#hikari.conf# file to read:

[.programlisting]
....
terminal = "/usr/local/bin/alacritty"
....

Will launch the `alacritty` terminal using the bound key press.
While going through the configuration file, it should be noted that the capital letters are used to map keys out for the user.
For example, the kbd:[L] key for starting the terminal kbd:[L+Return] is actually the previously discussed super key or Windows logo key.
Therefore, holding the kbd:[L/super/Windows] key and pressing kbd:[Enter] will open the specified terminal emulator with the default configuration.
Mapping other keys to applications require an action definition to be created.
For this, the action item should be listed in the actions stanza, for example:

[.programlisting]
....
actions {
  terminal = "/usr/local/bin/alacritty"
  browser = "/usr/local/bin/firefox"
}
....

Then an action may be mapped under the keyboard stanza, which is defined within the bindings stanza:

[.programlisting]
....
bindings {
  keyboard {
SNIP
    "L+Return" = action-terminal
    "L+b" = action-browser
SNIP
....

After Hikari is restarted, holding the Windows logo button and pressing the kbd:[b] key on the keyboard will start the web browser.
The compositor does not have a menu bar, and it is recommended the user set up, at minimal, a terminal emulator before migration.
The manual page contains a great deal of documentation it should be read before performing a full migration.
Another positive aspect about Hikari is that, while migrating to the compositor, Hikari can be started in the Plasma and GNOME desktop environments, allowing for a test-drive before completely migrating.

Locking the screen in Hikari is easy because a default [.filename]#pam.d# configuration file and unlock utility are bundled with the package.
The key binding for locking the screen is kbd:[L] (Windows logo key)+ kbd:[Shift] + kbd:[Backspace].
It should be noted that all views not marked public will be hidden.
These views will never accept input when locked but beware of sensitive information being visible.
For some users, it may be easier to migrate to a different screen locking utility such as swaylock-effects, discussed in this section.
To start Hikari, use the following command:

[source,shell]
----
% hikari -c ~/.config/hikari/hikari.conf
----

=== The Sway Compositor

The Sway compositor is a tiling compositor that attempts to replace the i3 windows manager.
It should work with the user's current i3 configuration; however, new features may require some additional setup.
In the forthcoming examples, a fresh installation without migrating any i3 configuration will be assumed.
To install Sway and valuable components, issue the following command as the root user:

[source,shell]
----
# pkg install sway swayidle swaylock-effects alacritty dmenu-wayland dmenu
----

For a basic configuration file, issue the following commands and then edit the configuration file after it is copied:

[source,shell]
----
% mkdir ~/.config/sway
% cp /usr/local/etc/sway/config ~/.config/sway
----

The base configuration file has many defaults, which will be fine for most users.
Several important changes should be made like the following:

[.programlisting]
....
# Logo key. Use Mod1 for Alt.
input * xkb_rules evdev
set $mod Mod4
# Your preferred terminal emulator
set $term alacritty
set $lock swaylock -f -c 000000
output "My Workstation" mode 1366x786@60Hz position 1366 0
output * bg ~/wallpapers/mywallpaper.png stretch
### Idle configuration
exec swayidle -w \
          timeout 300 'swaylock -f -c 000000' \
          timeout 600 'swaymsg "output * dpms off"' resume 'swaymsg "output * dpms on"' \
          before-sleep 'swaylock -f -c 000000'
....

In the previous example, the `xkb` rules for man:evdev[4] events are loaded, and the $mod key is set to the Windows logo key for the key bindings.
Next, the terminal emulator was set to be `alacritty`, and a screen lock command was defined; more on this later.
The output keyword, the mode, the position, a background wallpaper, and Sway is also told to stretch this wallpaper to fill out the screen.
Finally, `swaylock` is set to daemonize and lock the screen after a timeout of 300 seconds, placing the screen or monitor into sleep mode after 600 seconds.
The locked background color of 000000, which is black, is also defined here.
Using swaylock-effects, a clock may also be displayed with the `--clock` parameter.
See the manual page for more options.
The man:sway-output[5] manual page should also be reviewed; it includes a great deal of information on customing the output options available.

While in Sway, to bring up a menu of applications, hold the Windows logo key (mod) and press the kbd:[d] key.
The menu may be navigated using the arrow keys on the keyboard.
There is also a method to manipulate the layout of the bar and add a tray; read the man:sway-bar[5] manual page for more information.
The default configuration adds a date and time to the upper right-hand corner.
See the `Bar` stanza in the configuration file for an example.
By default, the configuration does not include locking the screen outside of the example above, enabling a lockout timer.
Creating a lock key binding requires the following line to the `Key bindings` section:

[.programlising]
....
# Lock the screen manually
bindsym $mod+Shift+Return exec $lock
....

Now the screen may be locked using the combination of holding the Windows logo key, pressing and holding shift, and finally pressing return.
When Sway is installed, whether from a package or the FreeBSD Ports Collection, a default file for [.filename]#pam.d# was installed.
The default configuration should be acceptable for most users, but more advanced options are available.
Read through the PAM documentation for more information.

Finally, to exit Sway and return to the shell, hold the Windows logo key, the shift key, and press the kbd:[e] key.
A prompt will be displayed with an option to exit Sway.
During migration, Sway can be started through a terminal emulator on an X11 desktop such as Plasma.
This makes testing different changes and key bindings a little easier prior to fully migrating to this compositor.
To start Sway, issue the following command:

[source,shell]
----
% sway -c ~/.config/sway/config
----

=== Using Xwayland

When installing Wayland, the `Xwayland` binary should have been installed unless Wayland was built without X11 support.
If the [.filename]#/usr/local/bin/Xwayland# file does not exist, install it using the following command:

[source,shell]
----
# pkg install xwayland-devel
----

[NOTE]
====
The development version of Xwayland is recommended and was most likely installed with the Wayland package.
Each compositor has a method of enabling or disabling this feature.
====

Once `Xwayland` has been installed, configure it within the chosen compositor.
For Wayfire, the following line is required in the [.filename]#wayfire.ini# file:

[.programlisting]
....
xwayland = true
....

For the Sway compositor, `Xwayland` should be enabled by default.
Even so, it is recommened to manually add a configuration line in the [.filename]#~/.config/sway/config# like the following:

[.programlisting]
.....
xwayland enable
.....

Finally, for Hikari, no changes are needed.
Support for `Xwayland` is build in by default.
To disable that support, rebuild the package from the ports collection and disable Xwayland support at that time.

After these changes are made, start the compositor at the command line and execute a terminal from the key bindings.
Within this terminal, issue the `env` command and search for the `DISPLAY` variables.
If the compositor was able to properly start the Xwayland X server, these environment variables should look similar to the following:

[source,shell]
----
% env | grep DISPLAY
----

[.programlisting]
....
WAYLAND_DISPLAY=wayland-1
DISPLAY=:0
....

In this output, there is a default Wayland display and a display set for the Xwayland server.
Another method to verify that `Xwayland` is functioning properly is to use install and test the small package:[x11/eyes] and check the output.
If the `xeyes` application starts and the eyes follow the mouse pointer, Xwayland is functioning properly.
If an error such as the following is displayed, something happened during the `Xwayland` intitialization and it may need reinstalled:

[.programlisting]
....
Error: Cannot open display wayland-0
....

[WARNING]
====
A security feature of Wayland is that, without running an X server, there is not another network listener.
Once `Xwayland` is enabled, this security feature is no longer applicable to the system.
====

For some compositors, such as Wayfire, `Xwayland` may not start properly.
As such, `env` will show the following information for the `DISPLAY` environment variables:

[source,shell]
----
% env | grep DISPLAY
----

[.programlisting]
....
DISPLAY=wayland-1
WAYLAND_DISPLAY=wayland-1
....

Even though `Xwayfire` was installed and configured, X11 applications will not start giving a display issue.
To work around this, verify that there is already an instance of `Xwayland` using a UNIX socket through these two methods.
First, check the output from `sockstat` and search for X11-unix:

[source,shell]
----
% sockstat | grep x11
----

There should be something similar to the following information:

[.programlisting]
....
trhodes  Xwayland   2734  8  stream /tmp/.X11-unix/X0
trhodes  Xwayland   2734  9  stream /tmp/.X11-unix/X0
trhodes  Xwayland   2734  10 stream /tmp/.X11-unix/X0
trhodes  Xwayland   2734  27 stream /tmp/.X11-unix/X0_
trhodes  Xwayland   2734  28 stream /tmp/.X11-unix/X0
....

This suggests the existence of an X11 socket.
This can be further verified by attempting to execute `Xwayland` manually within a terminal emulator running under the compositor:

[source,shell]
----
% Xwayland
----

If an X11 socket is already available, the following error should be presented to the user:

[.programlisting]
....
(EE)
Fatal server error:
(EE) Server is already active for display 0
	If this server is no longer running, remove /tmp/.X0-lock
	and start again.
(EE)
....

Since there is an active X display available using display zero, the environment variable was just set improperly, to fix this, change the `DISPLAY` environment variable to `:0` and attempt to execute the application again.
The following example uses package:mail/claws-mail[] as the application which needs the `Xwayland` service:

[source,shell]
----
export DISPLAY=:0
----

After this change, the package:mail/claws-mail[] application should now start using `Xwayland` and function as expected.

=== Remote Desktop Using VNC

Earlier in this document it was noted that Wayland does not provide the same X server style access as Xorg provides.
Instead, users are free to pick and choose a remote desktop protocol such as RDP or VNC.
The FreeBSD Ports collection includes the `wayvnc`, which will support wlroots based compositors such as the ones discussed here.
This application may be installed using:

[source,shell]
----
# pkg install wayvnc
----

Unlike some other packages, `wayvnc` does not come with a configuration file.
Thankfully, the manual page documents the important options and they may be extrapolated into a simple configuration file:

[.programlisting]
....
address=0.0.0.0
enable_auth=true
username=username
password=password
private_key_file=/path/to/key.pem
certificate_file=/path/to/cert.pem
....

The key files will need to be generated, and it is highly recommended they be used for increased security of the connection.
When invoked, wayvnc will search for the configuration file in [.filename]#~/.config/wayvnc/config#.
This could be overwritten using the `-C configuration_file` option when starting the server.
Thus, to start the `wayvnc` server, issue the following command:

[source,shell]
----
% wayvnc -C ~/.config/wayvnc/config
----

[NOTE]
====
At the time of this writing, there is no rc.d script to start `wayvnc` on system initialization.
If that functionality is desired, a local startup file will need to be created.
This is probably a feature request for the port maintainer.
====

=== Wayland Login Manager
While several login managers exist and are slowly migrating to Wayland, one option is the package:x11/ly[] text user interface (TUI) manager.
Needing minimal configuration, `ly` will start Sway, Wayfire, and others by presenting a login window on system initialization.
To install `ly`, issue the following command:

[source,shell]
----
# pkg install ly
----

There will be some configuration hints presented, the import steps are to add the following lines to [.filename]#/etc/gettytab#:

[programlisting]
....
Ly:\
  :lo=/usr/local/bin/ly:\
  :al=root:
....

And then modify the ttyv1 line in [.filename]#/etc/ttys# to match the following line:

[programlisting]
....
ttyv1 "/usr/libexec/getty Ly" xterm onifexists secure
....

After a system reboot, a login should appear.
To configure specific settings, such as language and edit [.filename]#/usr/local/etc/ly/config.ini#.
At minimal, this file should have the designated tty that was previously specified in [.filename]#/etc/ttys#.

[NOTE]
====
If setting ttyv0 up as the login terminal, it may be required to press the kbd:[alt] and kbd:[F1] keys to properly see the login window.
====

When the login window appears, using the left and right arrows will swap through different, supported, window managers.


=== Useful Utilities

One useful Wayland utility which all compositors can make use of is the waybar.
While Wayfire does come with a launch menu, an easy-to-use and fast taskbar is a good accessory for any compositor or desktop manager.
A Wayland compatible taskbar that is fast and easy to configure is waybar.
To install the package and a supporting audio control utility, issue the following command:

[source,shell]
----
# pkg install pavucontrol waybar
----

To create the configuration directory and copy over a default configuration file, execute the following commands:

[source,shell]
----
% mkdir ~/.config/waybar
% cp /usr/local/etc/xdg/waybar/config ~/.config/waybar
----

The `lavalauncher` utility provides a launch bar for various applications.
There is no example configuration file provided with the package, so the following actions must be taken:

[source,shell]
----
mkdir ~/.config/lavalauncher
----

An example configuration file that only includes Firefox, and is placed on the right, is below:

[.programlising]
....
global-settings {
	watch-config-file = true;
}

bar {
	output            = eDP-1;
	position          = bottom;
	background-colour = "#202020";

	# Condition for the default configuration set.
	condition-resolution = wider-than-high;

	config {
		position = right;
	}

	button {
		image-path          =     /usr/local/lib/firefox/browser/chrome/icons/default/default48.png;
		command[mouse-left] =     /usr/local/bin/firefox;
	}
	button {
	  image-path           =   /usr/local/share/pixmaps/thunderbird.png;
	  command[mouse-left]  =   /usr/local/bin/thunderbird;
}
....