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:

deb http://ftp.debian.org/debian sarge main contrib non-free

Should become:

deb http://ftp.debian.org/debian etch main contrib non-free

2. Update the system and install the xserver-xorg package:

apt-get update
apt-get upgrade
apt-get install xserver-xorg

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:

apt-get install udev

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:

$ cat /proc/bus/input/devices

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

I: Bus=0011 Vendor=0001 Product=0001 Version=ab41
N: Name="AT Translated Set 2 keyboard"
P: Phys=isa0060/serio0/input0
H: Handlers=kbd event0
B: EV=120013
B: KEY=4 2000000 3802078 f840d001 f2ffffdf ffefffff ffffffff fffffffe
B: MSC=10
B: LED=7

I: Bus=0011 Vendor=0002 Product=0005 Version=0000
N: Name="ImPS/2 Generic Wheel Mouse"
P: Phys=isa0060/serio1/input0
H: Handlers=mouse0 event1
B: EV=7
B: KEY=70000 0 0 0 0 0 0 0 0
B: REL=103

I: Bus=0003 Vendor=0a81 Product=0101 Version=0110
N: Name="CHESEN USB Keyboard"
P: Phys=usb-0000:00:10.2-1/input0
H: Handlers=kbd event2
B: EV=120003
B: KEY=10000 7 ff87207a c14057ff febeffdf ffefffff ffffffff fffffffe
B: LED=7

I: Bus=0003 Vendor=0a81 Product=0101 Version=0110
N: Name="CHESEN USB Keyboard"
P: Phys=usb-0000:00:10.2-1/input1
H: Handlers=kbd event3
B: EV=3
B: KEY=1f 0 20000 3878 d801d101 1e0000 0 0 0

I: Bus=0003 Vendor=04fc Product=0013 Version=06b0
N: Name="USB OpticalWheel Mouse"
P: Phys=usb-0000:00:10.2-2/input0
H: Handlers=mouse1 event4
B: EV=7
B: KEY=70000 0 0 0 0 0 0 0 0
B: REL=103

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)

/usr/local/lib

After that, run ldconfig:

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^[1]), 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:

chmod +x /usr/sbin/Xephyr.sh

For Ubuntu 8.04, the following command installs and updates the Xephyr binary

# apt-get install xserver-xephyr

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.

Section "ServerLayout"
	Identifier	"Layout"
	Screen		"Screen 1"
	Screen		"Screen 2"	Below	"Screen 1"
	Screen		"Screen 3"	Below	"Screen 2"
	.
	.
	Screen		"Screen N"	Below	"Screen N-1"
	InputDevice	"Generic Keyboard 1"
EndSection

2. Define one Device Section for each video card:

Section "Device"
	Identifier	"Video Card 1"
	Driver		"sis"	
	BusID		"PCI:0:5:0"	
	Screen		0	
EndSection
	#
	# Change the video card driver and the BusID according to your hardware.
	#
	# The BusID option identifies your video card. To obtain the BusIDs of your video cards,
	#use the command "lspci | grep VGA".
	# Beware: the lspci command shows address in hexadecimal, while X expects decimal numbers.
	#The command "echo $((0xHEX_NUMBER))" is your friend.
	.
	.
	.
Section "Device"
	Identifier	"Video Card N"
	Driver		"sis"
	BusID		"PCI:0:6:0"
	Screen		0	
EndSection

3. Define the Monitor Sections.

Section "Monitor"
	Identifier	"Monitor 1"
	HorizSync	30-71
	VertRefresh	50-160
	Option		"DPMS"
EndSection			
	.
	.
	.		
Section "Monitor"
	Identifier	"Monitor N"
	HorizSync	30-71
	VertRefresh	50-160
	Option		"DPMS"
EndSection

4. Define the Screen Sections

Section "Screen"
	Identifier	"Screen 1"
	Device		"Video Card 1"
	Monitor		"Monitor 1"
	DefaultDepth	24	
	SubSection "Display"
		Depth		24
		Modes		"1024x768" "800x600" "640x480"
	EndSubSection
EndSection
	.
	.
	.
Section "Screen"
	Identifier	"Screen N"
	Device		"Video Card N"
	Monitor		"Monitor N"
	DefaultDepth	24	
	SubSection "Display"
		Depth		24
		Modes		"1024x768" "800x600" "640x480"
	EndSubSection
EndSection

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

Section "InputDevice"
        Identifier      "Configured Mouse 1"
        Driver          "mouse"
        Option          "CorePointer"
        Option          "Device"                "/dev/input/mice"
        Option          "Protocol"              "ImPS/2"
EndSection

6. Xorg.conf should have only one keyboard section, like this:

Section "InputDevice"
    Identifier  "Generic Keyboard 1"
    Driver      "kbd"
EndSection

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:

Section "ServerFlags"
	Option "AllowMouseOpenFail"	"yes"
EndSection

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:

Section "ServerFlags"
       ...
	# Disable VT Switching
	Option    "DontVTSwitch" "yes"
	
	# This disallows the use of the Ctrl+Alt+Backspace sequence
	Option    "DontZap"       "yes"
       ...
EndSection

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:

apt-get install xdialog

2. Uncompress the file xkb-evdev.tar.gz on the directory /etc/X11.

3. Remove or rename the file /etc/gdm/gdm.conf:

mv /etc/gdm/gdm.conf /etc/gdm/gdm.conf.backup

[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:

update-rc.d configuracao_automatica start 70 S .

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

invoke-rc.d configuracao_automatica start

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

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.

rules = "evdev"
model = "pc105"
layout = "us"

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:

[servers]
0=Hardware
# Hardware is the main X server

1=Xephyr1
2=Xephyr2
3=Xephyr3
.
.
N=XephyrN
# Xephyr{1..N} is each one of the Xephyr servers

[server-Hardware]
name=Hardware
command=/usr/X11R6/bin/X
handled=false	
flexible=false
# The handled=false option hinders the login manager to be loaded on the main X server.

[server-Xephyr1]
name=Xephyr1
command=/usr/sbin/Xephyr.sh -display :0.0 -xauthority /var/lib/gdm/:0.Xauth -geometry 1024x768+0+0
-keyboard /dev/input/event0 -mouse /dev/input/event1,5 -use-evdev -dpi 92
handled=true
flexible=false
#
# The options -keyboard and -mouse identify, respectively, to which keyboard and mouse Xephyr will be associated, 
#as seen in the file /proc/bus/input/devices. If the mouse option finishes with ",5", as in
#the example, the mouse wheel will be activated.
#
# Xephyr.sh is the wrapper that runs Xephyr server.
.
.
.
[server-XephyrN]
name=XephyrN
command=/usr/sbin/Xephyr.sh -display :0.(N-1) -xauthority /var/lib/gdm/:0.Xauth -geometry 1024x768+0+0
-keyboard /dev/input/eventXX -mouse /dev/input/eventYY[,5] -use-evdev -dpi 92
handled=true
flexible=false

References

↑ Multiseat computer with Ubuntu 8.04

[1] Multiseat computer with Ubuntu 8.04

[1]