Virtual Network Computing
from ORL

MacVNC - VNC server for Macintosh

Alpha release - 1 Oct 1998 .

Note. This is an ALPHA release. As with all VNC software, you use at your own risk, but this bit is much more likely to crash your machine than the rest! You have been warned. The viewer is rather more stable. At present the server only implements the 'raw' encoding, so it will need a fast network. .
The source code will be available in the near future, after which we will welcome any bug fixes.

Use of the Mac server should be straightforward if you are familiar with the concepts behind VNC, and have a suitable VNC viewer running on another machine. Read 'What is VNC?' and 'Getting Started' if you haven't already done so - they'll give you a good overview, despite being Unix and Windows-orientated.

Requirements:

PowerPC Macintosh (for the server - the viewer is a FAT binary)
Open Transport 1.1.3 or better
A correctly configured TCP/IP connection
Display Manager better than 1.1 if you want display updates to be correctly handled

Installation:

Copy the contents of the ->Extensions folder to the "Extensions" folder inside your System folder.
Reboot the system
Select "Start Server" from VNC menu which should appear next to the applications menu. (If this doesn't work you may need to rebuild your desktop. Consult your manual as to how to do this)
Select "Server Options" from the same menu. Note: All server configuration is done through HTTP, so make sure Internet Config is set up correctly to start your favourite browser.
Set your preferred settings using the web browser.
Go to another machine and log on using a VNC Viewer or use a web browser to access http://<yourhost>:<port number> (The port number is displayed in the VNC menu. The default is 5800)

Note: You can also configure the server by using Apple Script. See the dictionary inside VNCServer for full details.

Question Index

How Do I ...

     ... stop other users changing the settings once I have set them?
     ... lock my server if I don't have ResEdit?
     ... know when the server is running?
     ... stop the server?
     ... use my command key from other machines?
     ... customise my html pages?
     ... paste into my Mac from a remote connection?
     ... communicate my feedback to ORL?

Why ...

... does my machine keep crashing?
... doesn't the Server Options.. menu item work?

How Do I....

Q. ... stop other users changing the settings once I have set them?

A. The vncPatches extension contains a vnc security resource that is easily editable using ResEdit or the Server Status Tool provided with the distribution (see below).
The resource is of type VCSc and its ID is 128. The options are:

Lock Server	If this flag is set the options for the server cannot be changed.
Status info available	If this flag is set, you can view the logs for the server by looking at http://<your host>:<portnumber>/log.html
My mouse has ... buttons	The server scans your desktop bus and tries to find a mouse. It identifies the mouse as being the first device with this number of buttons. You only need to change this if you have a mouse with more buttons.
Use error Prone updates	This relates to how ShowCursor is patched. See here for more details. Set to true for better server operation, set to false for more stability.
Allow Applescript to alter settings	Applescript can be used to control your VNC server and gather information about it. If you don't want this then clear this flag. You can use Script Editor to write Applescript scripts for the server.

So, if you want to lock your server, you need to set the first flag and then work out some way of preventing your users from altering the flag back again. This can be done by preventing write access to the system folder.

Q. ... lock my server if I don't have ResEdit?

A. Included in this distribution is a very simple Server Status Tool for setting the lock.

Q. ... know when the server is running?

A. The VNC menu icon should change to a light bulb when the server is running. Or choose About VNC... from the menu for more detailed information.

Q. ... stop the server?

A.. Select "StopThe Server" from the VNC menu. (Note: you may need to do this twice. This is a recognised problem and is being worked on).
Or run the following script from the script editor

   tell application "VNCserver"
         quit
    end tell

This script should work irrespective of whether the "Allow AppleScript" flag is set in the security resource.

Q. ... use my command key from other machines?

A. The modifiers that correspond to command can be set via the settings page or via Apple Script. The default is Left Alt and Left Control. So L Alt+ L Control + c is the same as command + c. Note: The command key is the one next to the space bar with a propeller symbol or an Apple symbol on it.

Up to four modifiers can be chosen and are described by thier X keysym values. See keysyms.h in the source distribution for more details of X keysyms. The default settings page has drop down menus to choose from a number of common modifiers. To add more modiifers to these menus put more <option value="0xNNNN">Key name</option> lines in the settings.tmpl file in the Html directory.
The modifiers can be set from AppleScript like this:

   tell application "VNCserver"
     set cmd equivalent to "ffe3 ffe9 0000 0000"
    end tell

The string is four 4 digit hexadecimal numbers describing the modifiers requested. (ffe3 ffe9 correspond to the default L Alt + L Control).

Note: Setting the modifiers to anything strange will produce "Current Modifiers: unknown" on the settings page. Do not panic. This just means that the server doesn't know how to describe the keysyms you've given it. They will still work, it's just the server doesn't have name for them.

Q. ... customise my settings/ logs / initial page?

A. The HTTP server look at the following places for HTTP files:

The directory specified in the Html directory line in the preferences file. (Default is the directory called Html in the same directory as the server)
Resources of type 'TEXT' inside VNCServer
Resources of type ' WWW' inside VNCServer (There's a space before the first W in ' WWW')
Resources of type 'JAVA inside VNCServer

You can therfore override the internal html files by putting new files in the Html directory.
Also, the server will transform certain filenames under cetain conditions:

Condition...	Maps ...	... to ...
Connection is local and the server unlocked	settings.html	settings.tmpl
Connection is not local and the server is unlocked	settings.html	localonly.tmpl
Server is locked	settings.html	noserver.html
Server is running properly	index.html or /	javastart.tmpl
Server is not running properly	index.html or /	noserver.html
Status info is available.	log.html	log.tmpl
Status info is not availble	log.html	noserver.html
Status info is available.	log<X>.html	single_log.tmpl
Status info is not availble	log<X>.html	single_log.tmpl

The <X> in the last two files is an ascii character from 0 onwards that describes which log number you want.
Log 0 is the main program log, log 1 is the http log, log 2 is a dcescription of status of the server and a list of active connections. Logs 3 and onward are the logs associated with the active connections. The logs are serverd via the template file single_log.tmpl. For example if a request for log0.html is received, the file single_log.html is used with the token $THELOG replaced with $LOG0 which is in turn replaced with the corect log.

Most of the html files served are passed through a template parser before being sent to the client. The template parser translates some tokens into useful information:

Token ... Expands to...

$SETTINGS_LINK <A href=<host>/settings.html>Settings</A> if the connection is local and the server unlocked. Nothiong otherwise.

$HOST The ip address of the host.

$WIDTH,$APPLETWIDTH The width of the screen

$HEIGHT,$APPLETHEIGHT The height of the screen

$LOG<X> The specified log. <X> is an ascii character starting at 0 which specifys the log

$MAINPAGE A fully formed URL to the index page

$PORT The port number for vnc connections (normally 5900)

$DESKTOP The user specified name of the desktop

$DISPLAY The display number. Normally 0

$MODIFIERS English description of the modifers that correspond to the command key

$THELOG A log. This token only works in single_log.html, which is only used when the user requests log<X>.html. See above for what the <X> means.

Settings can be changed by sending a POST event to the server, via a an HTML form.
The labels in the POST correspond to various variables:

Label... Variable ...

PASS The password

PAS2 The password again. It will be set if both of these are the same

DISP Display number

DESK Desktop name

Key1,Key2,Key3,Key4 The command key modifiers.

In response to a POST event (usually sent from the settings page) the server returns changed.tmpl unless the password was incorrectly set in which case passwrong.tmpl is sent.

Q. ... paste into my Mac from another machine?

A. The short answer is "You can't". The longer answer is "You can't because of the slightly odd way the Mac handles clipboards". This problem is being currently being investigated. Pasting from the Mac to other machine should work.

Q. ... communicate with ORL?

A. There is a VNC mailing list run by ORL that has a pretty large membership list and is read by all the VNC developers (not just the Mac one), so any questions you have can probably be answered by posting to this list. To join the list go here. Note that asking questions which are answered in this document or in the FAQ is a Bad Idea.

Why?..

Q. ... does my machine keep crashing?

A. VNCServer, in its fastest mode, breaks a general guideline in that it patches ShowCursor (which has to be interrupt time safe) with some code that isn't interrupt safe. This may sometimes cause bad things to happen. If this is happening to you you can switch to an interrupt safe version of ShowCursor by changing the "Use Error prone updates" flag in the security resource. See here for details. The downside is that updates that happen when the mouse button is down (like drags and menu operation) may not work so well.

Q. ... doesn't the Server Options.. menu item work?

A. The server options are set using a web browser via an HTTP connection. If your machine isn't set up for this already, you need Internet Config to make this work. From the IC faq:

Each new release of Internet Config is posted to MacGifts and is therefore available Info-Mac and UMich (and their mirror sites). It is also available from any site that holds Peter Lewis' software, namely AOL, AMUG, PopCo, Australia, Japan, and Switzerland.
Internet Config is also available as a NewsWatcher helper and on the TidBITS site.
Finally, all sorts of IC related material, including the latest version of the IC software, is available from the IC home sites in Australia and the USA.

Any comments regarding this program should be directed to the VNC mailing list.

go back to documentation

For comments, feedback, etc, please see the 'Keeping in touch' page.
Copyright 1998 - The Olivetti & Oracle Research Lab

Virtual Network Computing from ORL