MacVNC Server

© ORL - The Olivetti & Oracle Research Lab 1998.

Written by Charles McLachlan
 
What it does:
Allows your Macintosh to be viewed and used from a multitude of platforms and from anywhere in the world using a VNC viewer.

Licensing

MacVNC is part of the VNC system and is distributed under the terms of the GNU Public License. A copy of the license should be included with this distribution, but you can also find it at http://www.orl.co.uk/vnc/gpl.html .

Requirements

Installation

  1. Copy the contents of the ->Extensions folder to the "Extensions" folder inside your System folder.
  2. Reboot the system
  3. 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)
  4. 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.
  5. Set your preferred settings using the web browser.
  6. Go to another machine and log on using a VNCViewer 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: 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.
 

Q. ... 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.

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