MacVNC - VNC server for Macintosh

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. 

Note. This is a beta release. As with all VNC software, you use at your own risk!  We welcome bug fixes/ comments.

Requirements:

• A version of MacOS greater than 7.6.1,
• A Power PC machine
• Open Transport (1.1.3 or later).

Quick Start

• Drag vncPatches from the ->Extensions folder of the distribution onto a closed System Folder
• Drag the VNC Controls from ->Control Panels onto a closed System Folder
• Restart the machine
• Run VNCServer
• Run VNC Controls and set the password/ desktop name. Set display number to 0.
• Connect with a VNC client to <hostname>:0 or with a Java capable web browser to http://<hostname>:5800

Introduction

The Patches

The Server

The Control Panel

The first two options determine how your screen will be described to clients, the desktop name is what external viewers will see in their title bars, while the display number is what they'll have to add to your host name for them to connect properly (i.e. if you set the server running on machine 123.456.789.789 to have a display number of 0, then viewers can connect by specifying 123.456.789.789:0 or computer.room.place.com:0 as the host name).  The display number is NOT normally the TCP/IP port number (see web site for further details). The password box is (surprise, surprise) where you should enter your desired password. Only the first 8 characters will be used in authentication but it is case sensitive (i.e. thispassword is the same as thispassXXX but not the same as THISPASS).

Macintoshes have a key (the command key) that most other computers lack, which means that for an external client to send command key events, some sort of key press equivalent needs to be set. The four drop down menus specify which key combination will be used as command. For example, if you wanted your external clients to get command-c by pressing left control + right alt + F3 + c  you'd select "L Control", "R Alt", "F3" and "None" from the four menus. Other key presses can be set via the Apple Script interface.

The advanced button on the control panel takes you though to a slightly different set of options, which are described more fully on the panel itself.

If the VNC server preferences file is locked for any reason, no option settings will be allowed through any of the 3 interfaces. Also the web interface and the Apple Script interface can be disabled by setting the appropriate flags on the Advanced settings page.

Once the initial settings have been set, that's it. The server can be stopped by selecting Quit from the file menu or by pressing command- Q.

The Web Interface

All the html sent out by the server needs is kept in a directory called Html which should be in the same directory as the VNCServer binary. You can change the look of your server's settings page by changing the contents of this directory. Files ending .tmpl will be put through a template parser before being sent out, so in your customised html you can include things like $HOSTNAME  if you want to display your current desktop name. See the included .tmpl files for examples of other variables. You can change where the server looks for its html by changing the HtmlDirectory line in VNC Server preferences (found in the <startup disk>:System Folder:Preferences) or you can include the html/ tmpl files as TEXT resources inside the VNCServer binary. The names of the resources should be the same as the names of the files. Resources are searched before the Html directory.

The web interface can be disabled by removing the Html directory or clearing the "Use Http Options" flag on the Advanced screen of the VNC control panel.

The Apple Script interface

-- example for communicating with a VNC server

tell application "VNCServer"

     -- set the options to  sensible things

     set password to "password"

     set display number to 34

     set desktop name to "Bob's Computer"

     set cmd equivalent to "ffe3 ffe9 0000 0000"

     -- The following is a very esoteric option described more fully below

     set mouse id to "03045ef2"

     -- get a table of function use (very uninteresting)

     get stats

     -- Clear the previous statistics

     set stats to 0

end tell

cmd equivalent

mouse id

Question Index

     ... stop other users changing the settings once I have set them?
     ... use my command key from other machines?
     ... customise my html pages?
     ... paste into my Mac from a remote connection?
     ... communicate my feedback to AT&T Laboratories Cambridge?

Why ... 

     ... does my machine keep crashing?
     ... doesn't the Server Options.. menu item work?
     ... won't the control panel run unless the server has been run at least once before?

How Do I....

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

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

    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?

•   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

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?

Q. ... communicate with the developers?

Why?..

Q. ... does my machine keep crashing?

Q. ... doesn't the File/Options(HTTP).. menu item work?

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.
 

Q: ... won't the control panel run unless the server has been run at least once before?

A: The reason for this is that the panel either communicates directly with the server (through Apple Script) or alters its preferences file. If the server has never been run before, there will be no preferences file on the system and the panel won't be able to do anything.
 

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

go back to documentation