# Keystone README

### Contents

- What is Keystone?
- Servers
- Status
- Bugs
- Download
- FAQs
- Todo
- Credits
- References

### What is Keystone?

Keystone is a tool for KDE that allows you to remotely access the desktops of machines using the cross-platform VNC system. Keystone can access machines running a variety of operating systems (including most UNIX systems and Windows 95/98/NT/2000) providing they are running a VNC server. Note that Keystone is only a client program, you will need to download a server separately in order to use it.

The protocol used by Keystone (called RFB) was developed, and released as GPL by ORL (now the UK branch of AT&T research), they also wrote and maintain GPL servers for several platforms. You can find both information about the protocol and links to servers for a range of platforms on their website.

Keystone started life as a port of Markus Wuebben's kvncviewer program to KDE 2, but in the course porting the code, I have rewritten and redesigned most of the system. The new implementation builds on several new facilities that were not available in KDE 1, such as KPixmapIO and QSocket. There is so little of the original code left that I have decided on a name change, and to put the version number back to 0.1.

You can see a few screenshots of Keystone in action on my screenshots page. The screenshots may or may not reflect the look of the current version as I have some look and feel improvements planned.

### Servers

Most Linux distributions include the standard Xvnc server (usually run via the vncserver script), you can also download this and servers for other platforms such as MS Windows from the VNC website. If you have a problem with setting up a server then you should read the VNC FAQ, and if that does not help join the VNC mailing list. Do not mail me on this topic - I can't help and won't even reply.

I may in future write a server that operates in the same manner as the Win32 server for KDE. The Win32 server differs from the X11 server in that it does not virtualise the entire desktop. This has both advantages and disadvatages, it means that you can make an existing session available over the network, but only allows you to run a single server. I may also put a GUI together that makes it easy to configure the ORL server.

### Status

The current version is 0.4, and the following are now working:

- 0.1
  - Non-blocking socket handling
  - Authentication and logon
  - KDE 2 user interface
  - Raw and CopyRect encodings
  - Full screen mode
  - Grab keyboard mode
  - Graphics
  - Taking screenshots of the remote desktop
  - Event dispatching
  - Konqueror helper application support (you can run Keystone by entering a vnc: URL anywhere in KDE).
  - Options, login, password and about dialogs
- 0.2
  - XSHM support using KPixmapIO
  - Now uses KXMLGUI (thanks to Kurt)
  - Tru64 patch from Tom Leitner
  - Status reporting improvements
  - Config handling fixed
  - Recent connections list implemented
  - Update frequency respected
- 0.3 [KDE 2.0]
  - Portability fixes for FreeBSD (and maybe others)
- 0.4
  - Icons for the full screen mode now reflect the current state
  - Added a toolbar (optional of course)
  - Added support for the clipboard (you can cut and paste between the local and remote machines)
  - Added some what's this help to the options dialog

### Bugs

Version 0.4 contains the following known bugs:

- Custom about dialog is not shown
  I can't see a clean way to fix this without creating a complete custom help menu. For now I've left the standard about dialog in place.
- Crash when you connect to a non-existant server
  I can reproduce this every time, but I can't figure out what's wrong other developers have reported similar problems and they seem to be down to QSocket. The only known fix so far is to use KSocket instead. I'd prefer to fix the problem at the source, but I'm having no luck and I suspect QSocket may also be causing some other weird network issues I've seen, so if I can't track down the bug soon I'll give in and switch to KSocket like everyone else.

### Download

Keystone is available in the kdenetwork module of the KDE CVS, and is included in the KDE 2.0 release. The current version is 0.4. Note that Keystone requires KDE 2, you cannot use KDE 1.x.

### FAQs

- Why don't the shortcut keys work in full screen mode?
  When you're in full screen mode Keystone grabs the keyboard to send every key press to the remote screen. This means that you can send key combinations that are used by Keystone or KDE to the remote screen. If you really hate it, then you can add -nograb to the command line arguments to disable all keyboard grabs. I will add an option to allow this behaviour to be overridden in a future release.
- Why is Keystone so slow?
  Currently only the simplest of the RFB encodings are supported, this means that Keystone is only useful on fairly fast networks. This is a serious bug and is being addressed.

### Todo

These are the things I'm hoping to add to future versions of Keystone. They're vaguely sorted in order of importance.

- RRE encoding.
  I've started this, but the implementation has some bugs so it did not make the cut for Keystone 0.3.
- CoRRE and Hextile encodings
- Session management
- Support for Windows Terminal Server.
  There is now a GPL implementation of the protocol, and the author is happy for me to use the code. If someone can offer me an account to test it on then this is possible.
- Zoom support.
  This will be handled using the same protocol extension as is used in the Palm client, this will allow you to make use of server side scaling to reduce the amount of network traffic. You will also be able to do client side zooms, but in this case the full screen needs to transmitted over the network.
- Macros
- Monitor mode (thumbnails of several machines)
- ZLib extension support
- Bookmarks
- URL specific settings
- Possibly a DnD extension using a mechanism based on mulitpart MIME attachments.

### Credits

Keystone owes a lot to Markus Wuebben's kvncviewer which some of the code is derived from. Thanks are also due to Espen Sand the author of khexedit from which I borrowed some code for the about dialog. Alison Burch drew the bridge image used in the background of this page (and in future versions of Keystone too of course). Finally thanks go to ORL for making the RFB protocol and servers GPL.

### References

- The Keystone homepage
  http://www.ipso-facto.demon.co.uk/keystone/
- The VNC Homepage
  http://www.uk.research.att.com/vnc/
- The VNC FAQ
  http://www.uk.research.att.com/vnc/faq.html
- The KDE Homepage
  http://www.kde.org/

Last modified: Tue Dec 5 01:37:17 GMT 2000