Ubuntu Manpage: dxpc - Differential X Protocol Compressor

NAME

       dxpc - Differential X Protocol Compressor

RELEASE

       3.9.1

SYNOPSIS

       dxpc [common] [client | server] [connect]

       [common] options are:
            -p port_num -f -k -v -s debug_level -l log_file

       [client] options (valid for CLIENT process) are:
            -i compression_lvl -d display_num -u

       [server] options (valid for SERVER process) are:
            -D display -b(a|w)

       [connect] options are:
            hostname -w

DESCRIPTION

dxpc is an X protocol compressor designed to improve the speed of X11 applications run over low-bandwidth
links (such as dialup PPP connections).

dxpc must be run at both ends of a low-bandwidth link. On the host where the real X server is, dxpc runs
in "Server Proxy" mode. On the host at the other end of the link, dxpc runs in "Client Proxy" mode. The
Client Proxy dxpc must be started first. When the Server Proxy dxpc is started, it connects to the
Client Proxy. (Note that versions of dxpc before 3.3.1 used the opposite convention.) If either of the
two communicating dxpc instances is subsequently terminated, the other one automatically shuts down.

The Client Proxy mimics an X server. X client applications connect to the Client Proxy using display
"unix:8" (or "<hostname>:8"; dxpc supports both UNIX domain and TCP sockets). The Client Proxy receives
X requests from the application, compresses them, and sends them to the Server Proxy. The Server Proxy
uncompresses the requests and sends them to the real X server. Similarly, the Server Proxy receives X
events, replies, and errors from the real X server. It compresses these messages and sends them to the
Client Proxy, which uncompresses them and sends them to the client application.

The compression performance of dxpc depends upon the types of X applications being run. For many
applications, dxpc achieves between 3:1 and 6:1 compression of the X protocol traffic.

MODES

dxpc has two modes; the connection mode, which is either listening or connecting; and the X mode, which
is either client or server.

The listening process waits for a connecting process to initiate the TCP connection between the two
processes. The listening process must always be started first. The connecting process initiates the
connection to the listening process. dxpc will run as the connecting process if a hostname argument is
supplied (see connect options, above). Otherwise it will run as the listening process.

The server process is typically located on the same machine as the real X server, and is responsible for
displaying the output of applications. The client process is typically located on the same machine as the
X applications, and is responsible for forwarding the output of those applications to the server process.
By default, dxpc runs as the client process if it is the listening process (due to the lack of a hostname
argument) and the server process if it is the connecting process, but the -w switch reverses this.

For example, the command dxpc myhost.work.com starts dxpc as the connecting process (because a host name
is supplied) and the server process (because it is the connecting process and -w is not supplied). The
command dxpc -w starts dxpc as the listening process (because no hostname is supplied) and the server
process (because it is the listening process, and -w reverses the usual logic).

Options

-b(a|w) This option specifies that any windows created should be created with the BackingStore option
set to Always (-ba) or WhenMapped (-bw), if the application has not set the option itself.
Using the BackingStore option will reduce traffic to repaint exposed regions of the window,
at the cost of extra memory use in the X server itself. (This option is ignored in Client
Proxy mode.)

NOTE: The -ba option can cause Expose events to be sent before the client has mapped its
windows. This can confuse some client programs, notably GNU Emacs version 20.3. The "bug"
in this case is that dxpc shouldn't be setting BackingStore to Always behind the
application's back. Neverless, the option is available, if you want to try it; many client
programs still function fine with it, and it will cause the contents of iconified windows to
be retained.

-d displaynum
This option specifies the number of the X display that dxpc imitates. The default value is
8. (This option is ignored in Server Proxy mode.)

-f This option tells dxpc to fork and run as a daemon process. All subsequent non-error output
is suppressed, including statistics reports. The daemon can be killed by use of the -k
option.

-k This option tells dxpc to read a pid from the lockfile in the user's home directory and then
send a SIGKILL to the old process. It does some error checking to try to ensure that the
file contains a valid pid file (and nothing else). The pidfile will exist only if dxpc was
started with the -f option.

-l This option is used to tell dxpc to write messages and statistics to a logfile. Very useful
with the -f option.

-p portnumber
This option specifies the TCP port number to be used for communication between the Client
Proxy and the Server Proxy. The default value is 4000.

-s(1|2) Print a report on dxpc's compression performance for an X application when the application
exits. In Client Proxy mode, dxpc displays a report on the compression of messages generated
by the X client. In Server Proxy mode, dxpc displays a report on the compression of messages
generated by the X server. The -s1 option yields a simple report that provides the overall
compression ratio. The -s2 option yields a far more detailed report on the compression
ratios achieved for all the individual message types in the X protocol. The -s2 option is
the "hacker option"; most people will probably want the -s1 report instead.

-u -t Normally, dxpc in Client Proxy mode imitates an X display, :8 by default, by listening on
both a UNIX domain socket and a TCP socket. The -u option tells it not to use the UNIX
domain port, and the -t option tells it not to use the TCP port. (These options are ignored
in Server Proxy mode.)

-v This option tells dxpc to print out its version number and copyright message and exit.

-w Use of this option swaps the connection sequence. That is, the client will initiate the
connection to the server. Thus, instead of starting the client like dxpc -f and the server
as dxpc -f workserver, you can start the client as dxpc -w -f homepc and the server as dxpc
-w -f. This option is intended to be useful for people running the client proxy on a machine
behind a firewall.

hostname This argument must be used in Server Proxy mode to tell dxpc the hostname or IP address of
the machine where other dxpc (the one in Client Proxy mode) is running. (Note that the
presence of this argument is what puts dxpc in Server Proxy mode. If this argument is not
used, dxpc runs in Client Proxy mode.)

-D display Specify X host on which to display proxied applications. Defaults to value of the DISPLAY
environment variable.

-i(0..9|99|999)
This option controls bitmap image compression. This option is only valid on the instance
which is accepting connections; usually this is the client, but the -w option will reverse
this, making the -i option valid only on the server. The specified number is the image
compression level; higher levels offer better compression at the cost of greater CPU and
memory utilization (mostly on the client proxy). The actual behavior of each level is given
below.

0 : No compression (except for the very limited compression supported in dxpc 3.7.0). In
other words, behaves like 3.7.0 (but is incompatible with it)

1 : LZO lzo1x_1 compression; very fast, low CPU and memory use, reasonable compression.

2-9: LZO lzo1c_... variant compression algorithms. lzo1c_2 actually seems to be worse than
lzo1x_1...

99: LZO lzo1c_99 algorithm. Slow, but pretty good compression. NB: I have seen a couple of
unexplained crashes when using this level. Not recommended.

999: LZO lzo1x_999 compression. Slow (but fast enough to feed a 128K ISDN link when hosted on
a Pentium II/300 without maxing out the processor), but good compression. This is the default
and recommended value.

EXAMPLES

       Assume  that you're running a real X server on the console of a local workstation called homepc, and that
       you want to run some X applications on a remote system called workserver and have  them  display  on  the
       console of the local system.

       On workserver, run
            $ export DISPLAY=homepc:0
           $ dxpc -f
           $ export DISPLAY=unix:8

       On homepc, run
           $ export DISPLAY=unix:0
           $ dxpc -f workserver

       Now on workserver,
           $ xterm&
           $ xemacs&
           etc...

DXPC AND XAUTH

       If  you  use  X  authorization, with a .Xauthority file on the workstation where your real X server runs,
       you'll need to set up a .Xauthority file on the host where the ClientProxy runs.  One way to do this is:

       Copy your ~/.Xauthority file from the host where the real X server runs to  the  host  where  the  Client
       Proxy runs.

       Run
           xauth list
       to see the authorization keys.  There should be one for your real X display.  It will look something like
       this:
           <hostname>/unix:0   MIT-MAGIC-COOKIE-1   <hex string>
       On  the  host where the Client Proxy is located, add a new entry to the .Xauthority file with the display
       name of the fake X server (the DISPLAY where the Client Proxy is listening) and all of the  other  values
       from the entry for the real X display.  The xauth "add" command can be used, like this:
           xauth add <hostname>/unix:8 MIT-MAGIC-COOKIE-1  <hex string>
       where  <hostname> is the name of the host where the Client Proxy is running and <hex string> has the same
       value as the <hex string> obtained for the real X display in step 2.  Once you do  this,  you  should  be
       able to run X clients through dxpc successfully.

TROUBLESHOOTING

       Some  windows don't appear.  This can happen if the -ba option is used, and a client program (such as GNU
       Emacs version 20.3) does not request backing store and thus assumes that Expose  events  imply  that  the
       window has been mapped.  Use -bw, or leave out the -b option altogether.

       No  windows  appear.   This  can  happen if you are using a newer version of dxpc with an older one, from
       before the client and server roles were changed.  A connection can be established between them, but  both
       sides  believe  themselves to be the client side, or both sides believe themselves to be the server side.
       Make sure you're using the same version of dxpc at both ends of the connection.

AUTHOR

       Brian Pane

MAINTAINER

       Kevin Vigor (kevin@vigor.nu)

ACKNOWLEDGMENTS

       dxpc    has     adopted     many     good     ideas     from     the     HBX     and     FHBX     systems
       (http://www.cs.dartmouth.edu/~jmd/decs/DECSpage.html).

       Thanks to all of the users of dxpc who have contributed feedback and suggestions.