FF151 - Friend2Friend Server Management v0.6 2010-03-09
by Robin Upton (email: robin2010 (ȧt) altruists.org)
Alpha Version: A system in progress, areas in grey are not yet coded!
Friend2Friend (F2F) is a new scripting language to create programs which are interpreted over a network of XML virtual machines. This guide describes how to set up and manage an F2F server, which hosts a number of XML-VMs. It is intended for those interested in setting up an F2F server either as a platform for developing F2F software modules or for exploration of the Friend2Friend network.
Contents:
F2F Server Overview...... 2
Requirements...... 2
Installation...... 2
Configuration...... 3
Documentation...... 3
Server Management...... 3
Soft-system Management...... 4
Soft-system Debugger...... 4
Friend2Friend Server Overview
An F2F server exists to support F2F virtual machines. It is coded in immutable ‘hard’ code (currently, PHP5), as distinguished from the XML-Virtual Machines, termed soft-systems, to emphasise that they are made up of ‘soft code’ (XML). An F2F server is capable of supporting any number of soft-systems. This section describes how to install and configure an F2F server, and how to add and delete the soft-systems it supports.
Requirements
The first and currently only F2F server implementation is written in PHP 5.3. A webserver is highly recommended (though the code will run in PHP through a command line interface) and will be assumed from this point, since it provides a convenient interface to the F2F server. The current debugging GUI makes use of XUL, a Mozilla-specific technology, so use of a fairly recent version of Mozilla Firefox is assumed throughout.
Installation
The simplest way to install an F2F server is:
- Install a webserver that supports PHP5 (5.3 or later is recommended)
- The source code is available either with and without documentation. Both are available from
- Unzip into the folder in which you wish to run the F2F server
- Use a web browser to browse to [root folder]/hardcode/admin/install.php, which should present you with the first installation screen:
Fill in the hostname and IP address and click on “Step 2” to proceed to the next step:
This step offers a choice of sets of soft-systems to pre-install on the F2F server. On input of an administrator password of at least 8 characters, an “Install Friend2Friend” button appears, which installs the server as specified. The password controls the server’s administration interface by restricting access to the [rootfolder]/hardcode/admin/ folder.
Errors are reported in red and will stop the installation if they are fatal. Help is available at
Configuration
Most F2F administrators will not need to custom configure their F2F server, but for those interested in understanding exactly what functionality is installed by the server can refer to the XML files in the following folders, which are used by the install process:
Folder / Contents/installs / Sets of soft-systems available at step 2 of the installation process
/xvms / XML Virtual Machines (i.e. soft-systems) available to these installs
/core / Hard-coded F2F resources available to soft-systems on this server
/modules / Soft-coded F2F modules available to soft-systems on this server
/xvm-parameters / Parameters of the available soft-systems
/xvm-structures / Soft-nodes of the available soft-systems
Documentation
As well as hand written guides and presentations such as this file, F2F has a documentation module which directly compiles a lot of documentation from the XML configuration files. If your install has ready made documentation, see the [root folder]/docs folder, else make your own (by running the service) or see the online version at
Server Management
The server is managed by a GUI at [rootfolder]/hardcode/admin/control-server.php, the top of which provides information about the F2F server itself:
The most important link of this part of the GUI is the button, which recompiles the F2F /core and /modules folders. Compilation, a necessary step in the development of F2F soft systems, is explained further at
Soft-system Management
Each soft system on the F2F server has a corresponding line in the GUI such as
The top row describes the soft-system, and links to its structure (from the name) as well as another set of icons links:- (Soft-system folder), (Start Page), (Soft-system debugger),(Desktop), (Log folder), (Debug Outbox).
The bottom row describes the state of this soft system. As long as is checked, the server is polled to keep the information current. The soft system’s daemon scrolls the word ‘crunch’ if it is alive, and advances the crunch# and turns the gear wheels () if it is actually processing input. The and icons stop and start the daemon, while starts it and opens up a new tab to view the daemon’s debug output. (Note that only one such tab can be open at any one time, due to an HTTP limitation). A crashed daemon (due to a hardcode error) is indicated by a red icon, and should be reported to The extra icons provide easy access to this system’s XML logs: (/log folder), (Fatal error log), (Raw system log), (Rendered system log).
The line above is for installing new soft systems. Each needs a unique name, and a type as chosen from the drop down list. The PW: field is an optional chance to password access to its folder at [rootfolder]/soft-systems/[name]. The button adds the soft-system.
Soft-system Debugger ()
The soft-system debugger is an invaluable tool for development of new f2F software modules since it provides an easy way to send messages into a soft-system and to view their output. It is made up of 3 sections:
1)Pick Message, on the left, is a tabstrip of 4 sets of pre-defined messages useful for debugging: Core (for hard-coded services), Custom (for soft-coded services), Imports (services imported from other soft-systems) & Local (locally saved messages). Click on a message to load it into the second section of the debugger...
2)Edit & Input to the system..., is a syntax coloring editor for XML message content. The message header is hidden, though an icon () can display it if needed.
The following icons are available:- (Indent XML), (Highlight active request), (Lookup active request), (Toggle line wrap). The icon saves the message into the local messages folder, while the icon deletes it. The button feeds the message into the soft-system.
3)The state of the soft system is displayed in similar format as in the server management GUI:
The other part of this section displays a tabstrip of the messages output to /outbox/debug:
The tab of each message shows the crunch id when it was output from the soft-system. Fatal exceptions, such as that shown above, are marked with an icon.
The the top of this pane the checkbox controls polling the outbox, and whether to show acknowledgements. The icon links to the contents of the /outbox/debug folder, and brings up a full screen display of the outbox. The icon empties the folder.
Each tab has its own icon, which deletes this message, plus and icons to delete all preceding or following icons. It also has an icon to bring up a fullscreen display and an icon to reload this message. (The latter is needed to overcome a Firefox bug which randomly causes it to render the messages not as XML, but as XHTML - often resulting in a completely empty gray panel).
Public Domain under (cc) Robin Upton, 2010