# Multiseat Configuration/Xephyr

Here, we are going to describe how to make a Multiterminal with Xephyr. There are already a lot of different ways to build multiterminals (also known as multiseats), and new ways are constantly being developed.
The way described here uses modifications on Xephyr that make possible to use it in order to implement a multiterminal system. The system is configured to run one X server controlling all video cards, and one Xephyr for each screen, running above the main X server, the same way as with Xnest.
While normal Xephyr receives events from its parent X server, modified Xephyr now is able to read the input devices events directly from kernel event interface.

## Operating System required

Debian Etch (but it's easy to adapt it to other linux distributions).

## Introduction

Xephyr is an X server that runs inside another X server. Xephyr is both an X client and an X server, simultaneously. Xephyr is a client of the real X server, but also a server to its own clients. Xephyr is normally used to allow working on two or more desktops at the same time. However, we’ve made modifications to use Xephyr to implement a multiterminal system.
The system works in the following way. Only one «real» X server is run, configured to use several screens, each of which will be associated to one video card. After the X start-up, one Xephyr is run inside each screen. Each user will use one Xephyr, in a transparent way.
The original Xephyr gets the input devices events from its parent X server. However, to allow Xephyr to be used in the multiterminal, we had to modify its source code to make it read the events directly from kernel event interface, bypassing X. To read the mouse and keyboard events, the evdev protocol is used.
The great advantage of this approach is the possibility to make a multiterminal with any combination of video cards, as long as they are supported by the X. Besides that, Xephyr has several advantages over Xnest: Xephyr is being maintained, is faster than Xnest, and supports the implementation of X extensions more easily.

## Installing XOrg

Here are the steps required to configure a multiterminal system using the XOrg X-Server, although it is possible to use XFree86, with few changes. In order to use XOrg, you should be using Debian Etch or later, since Debian Sarge doesn’t have XOrg, only XFree86. If you are using Debian Sarge, follow theses instructions to update it to Etch:
Note: for most of the steps, you’re going to need to be the system Root. To do so, use the command 'su', and then type the root password.
1. Change the occurrences of «sarge» or «stable» in the file /etc/apt/sources.list to «etch», for instance:
Should become:
2. Update the system and install the xserver-xorg package:

## Evdev and Udev

Make sure your kernel is compiled with evdev support. Also install udev, which provides a dynamic /dev directory, updated according to the connected devices:
Udev requires a kernel 2.6 or newer.

## Input Devices

Now, you need to check if your input devices (mice and keyboards) have been correctly detected by the kernel. In order to do this, analyze the file /proc/bus/input/devices, which show details about the input devices detected by the kernel. Use the following command to see the contents of this file in a terminal:
An example of this file is shown below. Only two fields are of interest: the name of each device, shown in the lines starting with «N: Name=", and the name of the file related to each device, shown in the lines starting with "H: Handlers=".
Notice that the file seem to indicate the presence of 3 keyboards, although the system in question actually has only two. This happens because many USB keyboards have special keys (to control multimedia or access the internet, for instance), which are detected by the kernel as a secondary keyboard, whose physical address finishes with "input1». You need to configure only the primary keyboards, whose physical address finishes with «input0». Therefore, the section corresponding to the secondary keyboard’s physical adress «usb-0000:00:10.2-1/input1» will be ignored.
The example given show the presence of 2 «primary» keyboards, related to the files /dev/input/event0 and /dev/input/event2, respectively, and 2 mice, related to the files /dev/input/event1 and /dev/input/event4, respectively. These files are important, because they are used to relate each head of the multiterminal with the correct input devices.

## Ldconfig

Add the following line to the file /etc/ld.so.conf: (unnecessary in Ubuntu 8.04)
After that, run ldconfig:

## Modified Xephyr download

* Download the Xephyr binary here. Extract into the directory /usr/local. You can see the patches by clicking here (newer version for Xorg 7.2, Xorg 7.3 already has needed patches), but the patches are only needed if the user is going to compile it.
* Download the wrapper script necessary to run Xephyr: Xephyr.sh. The script must be copied to /usr/sbin and have executable permission. To give the file executable permission run the following command:
For Ubuntu 8.04, the following command installs and updates the Xephyr binary

## X(XOrg) configuration

To configure a multiterminal with N terminals, edit the file /etc/X11/xorg.conf, and do the following:
1. Define a layout with N screens.
2. Define one Device Section for each video card:
3. Define the Monitor Sections.
4. Define the Screen Sections
5. The keyboard definition can be the same as the already existing in your xorg.conf, however, certify that the Identifier is the same as defined on Section Layout («Generic Keyboard»). It is needed to make the mouse point to the device /dev/input/mice
6. Xorg.conf should have only one keyboard section, like this:
7. To avoid problems on the X Server initialisation caused by the not recognizing of the mouse, you can include, without problems, the following section:
Ps: That will not affect the multiterminal because the keyboard/mice devices will be passed as parameters to the Xephyr.
8. Finally, to disable the VT changes and the Ctrl+Alt+Backspace keys, verify that the section «ServerFlags» has the following options:

## Layout configuration
### Using a script

Because the input devices detection (mice, keyboards) made by the kernel (see section «Input Devices») doesn’t always follow the same order, it is possible that the kernel will associate the same device with different files, in each initialization, and that may «shuffle» the keyboards and mice.
To avoid this problem, we made scripts that automate the mice and keyboards association process to their respective displays. It is just needed to configure the layout (which keyboard and mouse are associated with which display) one time, and the script will keep this «layout» on the file /etc/X11/devices.conf. To use the script, follow these steps:
1. Install the xdialog package:
2. Uncompress the file xkb-evdev.tar.gz on the directory /etc/X11.
3. Remove or rename the file /etc/gdm/gdm.conf:
[edited on 04/11/2007] Perhaps the mods should be edited into the /etc/gdm/gdm.conf-custom file, which will not be overwritten by an update.
4. Uncompress the file public.tgz and copy the files «configura_layout» and «select.out» to the directory «/usr/local/sbin». Then copy the file «configuracao_automatica» to the directory «/etc/init.d».
5. Configure configuracao_automatica to be executed on the system initialization:
6. Execute the following command to configure the system layout. The script will ask questions for each display to determine which keyboard and mouse is associated with each monitor.
PS: Before doing this, you must stop «gdm». Enter as root and type «/etc/init.d/gdm stop».
The script will automatically generate the file /etc/gdm/gdm.conf if it doesn’t exist, as well as the XKB configuration files (/usr/X11R6/lib/X11/xkb/XX-config.keyboard). The script will create links on the /dev/input directory, called kbd0mt, kbd1mt, etc., that refer, respectively, to the keyboard of the first terminal, the keyboard of the second terminal, and so on. The script will also create links called mouse0mt, mouse1mt, etc., that refer, respectively, to the first terminal’s mouse, to the second terminal’s mouse, and so on.
After answering the questions, the script will generate the /etc/X11/devices.conf file, which will contain each terminal’s mouse and keyboard associations, and the keyboard configurations (rules, model, layout).
Another possibility to get the correct matching between the physical input devices and the event numbers is to modify the Xephyr wrapper script. The wrapper has been modified to obtain the event id from the physical device address. You can see the modified script here:

### Manual configuration

If you used the script from the «using a script» section, don’t follow these steps. However, reading this section will provide and understanding about how the script works.

#### XKB configuration

In order to allow Xephyr to use the XKB extension, you should uncompress the file xkb-evdev.tar.gz into the directory /etc/X11. After that, it’s necessary to create an XKB configuration file for each Xephyr. The XKB configuration for the first Xephyr should be placed in the file /usr/X11R6/lib/X11/xkb/X1-config.keyboard, for the second Xephyr in /usr/X11R6/lib/X11/xkb/X2-config.keyboard, and so on. You can see an example of an XKB configuration file below.

#### GDM configuration

The last step is to configure the login manager to start the main X server and also to run the wrapper scripts that will open Xephyr. We’ll explain how to do this on GDM, but other managers, like XDM and KDM, can be configured in a similar way.
Edit the file /etc/X11/gdm.conf in the servers section, adding the following:

## References

* ↑ Multiseat computer with Ubuntu 8.04