Home Page

Installation Instructions

General Warning

Since this software is in development stage, it is not meant for use in production machines. Please use this software only for developing or testing purposes.

Downloading the Sources

Download the XFree86 server sources. The following table lists the source files you need to download. The files marked as optional contain the fonts and the documentation distributed with XFree86: you may optionally install those too, if you wish.

Unpack the XFree86 sources in a directory, e.g. ~/X. The source tree root will be ~/X/xc. (If you are using XFree86 4.2.1, apply the 4.2.0-4.2.1.diff.gz patch now)

Optionally, download the OpenSSH sources. Unpack the tar file in ~/X/openssh-sss, where sss is the current version of OpenSSH.

From the summary page of this project, download the latest version of the following files:

• xsupervisor-XFree86-xxx-vvv.diff.gz XFree86 server patch
• xsupervisor-client-vvv.tar.gz supervisor client prototype
• xsupervisor-openssh-sss-vvv.diff.gz OpenSSH patch (optional)

where vvv is a version number for each package. Make sure that xxx matches with the version of the server sources and that sss matches with the version of the OpenSSH sources (if you downloaded them).

If you instead want to use the CVS, download the server patch following these instructions.

Building the Server, the Client and (Optionally) OpenSSH

Apply the server patch by changing to the ~/X directory and running

$ gzip -dc xsupervisor-XFree86-xxx-vvv.diff.gz | patch -p0

Then, compile the server as usual (make World). You may make install, but you do not have to. You can run the server from the source tree by running XFree and Xnest in the tree: in that case, you may have to adjust the LD_LIBRARY_PATH environment variable to point to the compiled libraries path.

Unpack the client in the ~/X directory, thus creating the ~/X/xsupervisor-client-vvv directory. Change to that directory, and type xmkmf to procuce the Makefile. If you did not install XFree86, you have to type xmkmf ~/X/xc to point to the root of the source tree. Build the client with make.

If you downloaded OpenSSH and the related patch, apply the patch by changing to the ~/X directory and running

$ gzip -dc xsupervisor-openssh-sss-vvv.diff.gz | patch -p0

Build (and optionally install) OpenSSH as usual. Using the patched OpenSSH, you should able to set the new option ForwardTrustedX11 to either yes or no to mark clients from that host as respectively trusted or untrusted.

Running the Supervisor

Start the patched server (even Xnest is fine). Make sure the server is started with a X Security cookie in the auth file. Moreover, you should set the XAUTHORITY environment variable to the auth file. See the xauth man page for more information. A simple way of doing this is to run this shell script (you may have to change the first variables):

#!/bin/bash

SRC=~/X/xc                        # the XFree86 source tree root
export NEW_DISPLAY=:1             # a free display number
export NEW_XAUTHORITY=~/X/Xauth   # a file for the trusted cookie

rm -f $NEW_XAUTHORITY
xauth -f $NEW_XAUTHORITY <<EOF
add $NEW_DISPLAY . `mcookie`
EOF
$SRC/programs/Xserver/Xnest $NEW_DISPLAY \
     -terminate -auth $NEW_XAUTHORITY &

# now start a window manager for the new server
export DISPLAY=$NEW_DISPLAY
export XAUTHORITY=$NEW_XAUTHORITY
sleep 2
$SRC/programs/twm/twm &

In the patched server, open an X terminal emulator (such as xterm) and start the supervisor client with it by running ~/X/xsupervisor-client-vvv/xsupervisor. No supervisor window should appear right now. Usually you will have to set the LD_LIBRARY_PATH environment variable to the path of the new, patched libraries. This is usually done with:

$ cd ~/X/xsupervisor-client-vvv
$ LD_LIBRARY_PATH=~X/xc/exports/lib:$LD_LIBRARY_PATH xterm \
  -e ./xsupervisor &

Testing the Supervisor

To actually see the intervention of the supervisor, you have to try to violate the server security policy with an untrusted client. For instance, you can run an untrusted client by using the patched OpenSSH and connecting to some host with the option ForwardTrustedX11 no: all the forwarded client will be untrusted.

Alternatively, if you have not built the patched OpenSSH, you can create a new untrusted terminal emulator with the following commands:

$ xauth -f ~/X/Xauth.unt generate $DISPLAY . timeout 0 untrusted
xauth:  creating new authority file ~/X/Xauth.unt
$ XAUTHORITY=~/X/Xauth.unt xterm &

All the clients launched from this terminal emulator will be untrusted too.

Now, if you try to do something that triggers the internal server policy (e.g. to copy&paste text from an utrusted client to a trusted one, or viceversa), a supervisor dialog should pop up. The dialog should disclose at least the following information:

• the subject of the action, i.e. the untrusted client that attempted to do a possibly dangerous operation;
• the type of action, i.e. what the client was attempting to do (which suspicious X request was sent);
• the object of the action, i.e. which resource would be affected by the action (for instance, a window)

The dialog will let you choose whether the request should be allowed or rejected.

That's all. Have fun.

Using CVS Instead of the Released Packages

$ export CVSROOT=:pserver:anonymous@cvs.xsupervisor.sourceforge.net:/cvsroot/xsupervisor
$ cvs login
Password: (press enter here)
$ cvs rdiff -u -r xf-XXX-orig -r xf-XXX xc | gzip -c > xsupervisor-XFree86-XXX-cvs.diff.gz

Further information can be found in the project summary page.

The OpenSSH patch and the supervisor client are currently not kept in the CVS.

Last update: 11 Mar 2003 by zunrob