Readme for gemsvnc

Readme for gemsvnc: Information about gemsvnc

R. J. Brown -- Elijah Laboratories Inc.
Code licensed under the GPL, Documentation licensed under the GFDL

The gemsvnc program is a remote frame buffer server, also called a VNC (Virtual Network Computing) server. It is intended to be connected to by a VNC viewer, preferably the TightVNC vncviewer.

Unlike most Unix hosted VNC servers, which are also X-servers, and serve an X environment that they maintain internally, gemsvnc, like its predecessors x0rfbserver and x11vnc, which is distributed with libvncserver, is only a VNC server, but not an X-server. It attaches to an already running X-server and permits remote control of that X-server from the vncviewer. This is desirable when one is using vnc for a customer service or training tool, or where special graphics hardware (such as openGL) is being used so that a normal vncserver would not work.

The gemsvnc program inherits good things from both X0rfbserver and x11vnc. It is in fact directly descended from x11vnc. X0rfbserver is the earlier program, but it was written in C++ before the libvncserver library was available. The libvncserver library is written in C, as is x11vnc. The gemsvnc program uses libvncserver because that library supports tight encoding and jpeg encoding, both of which are important for fast response over slow networks. the x0rfbserver program does not support these performance enhancements.

The x0rfbserver program does use a much more efficient framebuffer scanning algorithm than x11vnc, and gemsvnc expands on the x0rfbserver algorithm by permitting variable tile sizes, whereas x0rfbserver fixes the tiling of the framebuffer to 32 by 32 squares. The tiles may be any size between 1 by 1 and width by height, where these latter are the pixel dimensions of the entire framebuffer. In x0rfbserver, the tiles are scanned using an interlace pattern that is hard coded as an initialized array, but in gemsvnc, the interlace pattern array is initialized by a dynamically generated interlace sequence to fit the specified tile dimensions.

In x11vnc, there is no support to display the location of the mouse cursor on the real X-server. In x0rfbserver a mouse cursor is displayed, but it does not change shape to correspond to the shape actually being displayed on the real X-server. This same level of mouse support is provided by gemsvnc. It is not obvious how a vnc server can obtain the information necessary to display the same mouse cursor shape that the real X_server is displaying at any moment. The closest thing I can figure out how to do is to obtain the resource identifier of the mouse cursor visual, but given that, I cannot figure out how to get the actual graphic. For this reason, the position of the real X-server's mouse cursor is displayed, but the shape is locally determined by gemsvnc, not by the actual shape being displayed on the real X-server.

A unique enhancement found in gemsvnc is the ability to specify regions of the display that have special properties. These regions are always rectangular, with the sides parallel to the display edges. A region may be specified as either of category "hold", "image", "guard", or "block".

The "hold" category has no particular effect, and acts only as a place to park such a region when it is desired for it to be inactive, but retain the ability to activate it later.

The "image" category is used to specify a region of the screen that contains an image, such as a photographic image. This region will be updated in its entirity whenever any part of it is determined to have changed. This approach prevents the chunkiness caused by updating a larger region a tile at a time. Since such images usually change everywhere if they change anywhere, this approach also conserves bandwidth and gives faster response.

The "guard" category is used to specify a region of the screen in which the remote vncviewer is not permitted to perform input. This is useful to protect certian buttons, fields of forms, etc. from remote manipulation. The remote viewer can still see these regions, but these regions will be indicated visually to the remote viewer by being tinted with a transparent color (the default is green, but this is overridable by a command line option), and by a change in the remotely displayed mouse cursor from a pointer to a "no-sign" -- a circle with a diagonal line thru it.

The "block" category is used to specify a region of the screen where the remove viewer is permitted to neither see nor perform input. This is useful when there is sensitive information being displayed on the real X-server, and the remote viewer is not supposed to have access to that information, but he still needs access to other parts of the real X-server display. These regions will be indicated visually to the remote viewer by being colored with an opaque color (the default is orange, but this is overridable by a command line option), and by a change in the remotely displayed mouse cursor from a pointer to a crying "frowney-face".

The control of these rectangles is through a command language. There are commands to create and destroy rectangles, to specify their position and size, and to specify which category they belong to. There is also a command to display the status of a rectangle, or group of rectangles. These commands are all issued from stdin, and the response to a command is sent to stdout. In the future, there will be a port that can be connected to so that multiple applications running on the X-server being monitored by gemsvnc can control the rectangles over sockets. This socket interface is not yet implemented.

The comments at the top of the file commands.c fully document the rectangle command language:

This file implements the command language for gemsvnc. This language is used by X clients to control certain aspects of the gemsvnc rfb server. These commands may be issued from stdin, in which case the response to them will be issued to stdout, or these commands may be issued from a socket that connects to a well known port. (The socket interface is not yet implemented, but is a logical extrapolation of the stdin/stdout interface.) The model is enquiry-response: when a command is issued, it will receive some sort of response. The default SUCCESS response, in the absence of any other output, is "OK" followed by a newline.

Where a <name> is called for, a regular expression is permitted, except in the case of the "new" command, in which case the <name> must be absolute. In all other cases, if <name> is a regular expression, the command will be carried out on all names matching <name>.

The following commands are implemenmted:
block <name> Do not allow the remote viewer to see region(s) <name>. Show the region(s) as opaque in the -block color (default orange). Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. guard <name> Do not allow the remote viewer to input keystrokes or mouse button presses into region(s) <name>. Show the region(s) as transparently tinted in the -guard color (default green). Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. hold <name> Place region(s) <name> into the hold state. Regions in the hold state maintain their identity and position, but have no effect on the operation of the gemsvnc server. This is a sort of "holding tank" for regionms that may not be fully configured, or that temporarily need to be placed out of service. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. image <name> Place region(s) <name> into the image state. The video in these regions will be updated in their entirety whenever a change of any part of them is detected. The intent is that such a region has an image in it, and so if any pixel of the image changes, then practically all of the image is likely to have changed, so just update the entire region at once. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. kill <name> Destroy the region(s) <name>. This removes the region(s) and their name(s), thus making the name(s) available for re-use. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. new <name> Create a new region named <name>. In this case, <name> is *NOT* a regular expression. Only a single region can be created with a single issuance of this command. The region is at an indeterminate location, and is placed into the hold state. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NAME ALREADY IN USE The name is already used by an existing rectangle. place <name> ulx uly lrx lry Place the region(s) <name> at the specified location on the screen. The region is always a rectangle, and is described by its upper left and lower right corners. Each corner is described by its X and Y coordinates. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. BAD NUMBER FOR ULX The upper left x coordinate is not a number. BAD NUMBER FOR ULY The upper left y coordinate is not a number. BAD NUMBER FOR LRX The lower right x coordinate is not a number. BAD NUMBER FOR LRY The lower right y coordinate is not a number. RECTANGLE IS INSIDE-OUT The upper left corner is on the wrong side of the lower right corner. BAD REGULAR EXPRESSION The <name> regular expression is ill-composed. show <name> Show the location and state of region(s) <name>. This will output 1 line for each region. Each line will start with contain, in order, the name, state, and location, as follows: NAME STATE ULX ULY LRX LRY with a single space between each field. This will be followed by the "OK" response. Responses: OK The command was successful. MISSING NAME No <name> regular expression was provided. GARBAGE AT END OF LINE Non-whitespace after <name>. NO NAMES MATCH No names matched the regular expression <name>. BAD REGULAR EXPRESSION The <name> regular expression is ill-composed.
The gemsvnc server supports all the command line options provided by libvncserver, plus additional options that are described by running gemsvnc with the -help option: Usage: gemsvnc {options}, where the options are either libvncserver options or gems-specific options. These are the gemsvnc specific options:
-help Display this help message. -display Specify the display to attach to. -wait4client Specify the time-out to use when waiting for a client to connect. -update Force an update of all connected clients. -noshm Do not use the MIT X shared memory (SHM) extension even if it is available. -runforever Do not time out waiting for a client, and do not exit after the last client has disconnected. -viewonly Only permit the remote view to view, but not to interact with the display being served. -shared Allow multiple clients to be connected simultaneously. -scans Specify the number of the framebuffer scans between sampling for input events or sending framebuffer updates. -tw Specify the width in pixels of the tiles the framebuffer is divided into. -th Specify the height in pixels of the tiles the framebuffer is divided into. -bc Specify the blocked region opaque color, default is orange. -gc Specify the guarded region transparent color, default is green. -events Specify the maximum number of input events before a screen update is forced.
These are the libvncserver specific options:
-rfbport port TCP port for RFB protocol -rfbwait time max time in ms to wait for RFB client -rfbauth passwd-file use authentication on RFB protocol (use 'storepasswd' to create a password file) -passwd plain-password use authentication (use plain-password as password, USE AT YOUR RISK) -deferupdate time time in ms to defer updates (default 40) -desktop name VNC desktop name (default "LibVNCServer") -alwaysshared always treat new clients as shared -nevershared never treat new clients as shared -dontdisconnect don't disconnect existing clients when a new non-shared connection comes in (refuse new connection instead)

The options most important to tuning gemsvnc for a particular application and speed of network are -tw, -th, -scans, -events, and -deferupdate. The -rfbport is required if more than a single instance of gemsvnc is to be run concurrently on the same machine.

The vnc viewer that is used to view the X-server that is being relayed by gemsvnc should be the vncviewer available from tightvnc.org, as other viewers do not support the high compression modes that give good performance even over slower network connections. The tightvnc vncviewer should be set to use custom compression level 9 and jpeg quality level 0 along with tight compression to achieve fastest response. It must be emphasized that these parameters are chosen by the vncviewer, and not by the gemsvnc server, and that these are not the default settings that the tightvnc vncviewer starts up with.