Table of Contents:

Introduction

• Server 8 Architecture

Server 8 Configuration File

• XML and Other Conventions

Server 8 Registry

• Registry Path Syntax
• Main Registry Lists
• Registry Viewer

The Adminfs Plug-in

• Server-Side JavaScript
• Server-side JavaScript Error Handling
• RMA JavaScript Extensions
• Special Server-Side Tags
• HTTP Headers

Special URLs

• Configuration URLs
• Configuration URL Parameter Rules
• The Response Page Parameter
• Displaying Configuration Change Results
• Handling Configuration Failures
• Additional Server URLs
• Authentication URLs

Customizing RealSystem Administrator

• Customization Simple Example
• RealSystem Administrator Layout
• Integrating Your Web Page Within RealSystem Administrator
• Adding a Page to the Table of Contents Frame
• Conclusion

Appendix A – The Sandbox Approach: Adding A Second RealSystem Administrator Directory for Development

Appendix B - Additional Resources for RealSystem Administrator Developers

Glossary

Introduction

This white paper provides the scripting details of RealSystem Administrator, the Web-based management application for Server 8 (as well as the previous versions of RealServer G2 and RealServer 7.0.) It is targeted at developers interested in extending the Administrator to manage their custom plug-ins, and assumes a solid understanding of HTML and JavaScript.

The first section of this white paper introduces the key architectural components of Server 8 and its RealSystem Administrator, including the configuration file and server registry. The second section details the functionality provided by the Administrator file system plug-in (referred to as the adminfs plug-in) for setting and retrieving configuration data from the server registry. In closing, Appendix A demonstrates a sample extension of the RealSystem Administrator, while Appendix B collates additional developer resources.

Server 8 Architecture

Server 8 was designed on an architecture that allows greater extensibility and interoperability with third-party solutions. This extensibility is possible by using a COM-based plug-in architecture. Using the RealSystem Software Development Kit (SDK), a developer can create custom Server 8 plug-ins for monitoring, logging, filtering, and extending the server. Managing custom plug-ins is easy, due to the extensible nature of the Server 8 configuration file and registry, and the server-side scripting capabilities provided by the adminfs plug-in.

The following diagram outlines the communication flow among Server 8 and RealSystem Administrator components:

The Server 8 configuration file is an XML-based file which defines all of the server's operating parameters, such as mount point locations, ports, directories, and other properties. The default configuration file (rmserver.cfg) is installed in the RealServer directory. At start up, Server 8 loads the configuration file into the server registry, where its properties become available to the server, plug-ins, and the RealSystem Administrator Web application. Changes made through the Administrator are then written to this configuration file.

The excerpt below illustrates the hierarchical nature of the configuration file, as well as the fact that developers are free to add their own sections to the configuration file for use by their custom plug-ins. Any customizations to the configuration file are automatically reflected in the Server 8 registry, after restarting the server. The configuration file's syntax and contents are described fully in the Server Administration Guide, published at http://service.real.com/help/library/guides/server8/realsrvr.htm.

<!--            M Y   C O N F I G   S E C T I O N          -->
<!--            ---------------------------------          -->
<List Name="MyPropertyList">
  <Var Protocol="TCP"/>
  	<Var Timeout="30"/>
</List>

The server's registry is a hierarchical structure of lists of name/value pairs (properties), capable of storing string, buffer, and integer data types. Properties are organized into lists and sub-lists. Each list in the registry acts like a private name-space, meaning that while property and list names must be unique within a list, you can reuse them in other lists.

At runtime, this registry contains configuration information, Server statistics, and system status. RealSystem Administrator Web pages have read-only access to the registry via special server-side Javascript functions and HTML tags. Data that you type into the Web page fields can be transmitted on-the-fly via special URLs, recognized by the adminfs plug-in, to modify the server registry and/or configuration file. "On-the-fly" means the changes are written instantaneously, as the Server 8 is running. There is no need to restart Server 8.

Registry Path Syntax

Registry lists and properties are identified by property paths, with the "." character used as the path separator between sub-lists. Using the example above in the My Config Section, you would specify the Protocolproperty in the MyPropertyList using this notation:

MyPropertyList.Protocol

This path notation applies to the SDK's registry, to the JavaScript extensions supported by the adminfs plug-in, and when using the special Administrator URLs. Note that the use of the "." as a path separator excludes the use of the "." character in list names, and that list and property names are case-sensitive.

The server registry is partitioned into several major sub-lists, detailed in the table below. Conceptually, it is important to understand that the server registry is not related to the Windows system registry---it is specific to Server 8.

The Registry Viewer

Server 8 has a useful tool called the registry viewer. This tool allows you to search your machine's registry to find particular data types. You can access the viewer with this URL: http://yourserver:adminport/admin/regview.html.

adminfs stands for the Administration File System plug-in. This plug-in (named admi3260.dll on a Windows system, adminfs.so.6.0 on UNIX) is used by Server 8 to fulfill requests for URLs using the /admin/ mount point and admin port. The Adminfs plug-in executes server-side JavaScript and other special tags in each page it serves. This plug-in also responds to several virtual URLs that allow the client to:

• modify the server’s registry and/or configuration file
• restart the server
• manage the server’s user database(s).

The adminfs plug-in hosts a JavaScript runtime engine, based on Netscape's version 1.4 of the core Javascript language. Netscape’s Server-Side JavaScript extensions are not supported in adminfs, but adminfs adds its own extensions to access the Server 8 registry, and to send output to the HTTP client. These functions are detailed below.

To run JavaScript on Server 8, enclose script statements in <SERVER language="JavaScript"></SERVER> tags. Note that the adminfs plug-in requires that the "language" attribute in the <SERVER> tag be all lower case, as in the example above. This applies to RealServer version 7.0 and earlier. To emit output to the HTTP client, adminfs provides a function called RMAOutput(). The link below leads to a demonstration of a page with a simple example of server-side scripting, adminfs-style.

A Simple Server-Side Javascript Example

Server-Side JavaScript Error Handling

If an error is encountered in server-side Javascript (due to syntax or run-time) the error message will be inserted into the HTML document in the form of an HTML comment. Use your browser's "View Source" function to view the error message. If your page doesn’t look or function properly, always check the source code for server-side errors. Also, keep in mind that if your client-side script depends on your server-side script, then the browser may display client-side errors when the actual mistake is in the server-side script. When in doubt, always use your browser's "View Source" function to troubleshoot.

Sample with intentional server-side JavaScript Error
Sample View Source of error message

In addition to the RMAOutput function mentioned above, the adminfs plug-in provides a set of functions for accessing the Server 8 registry. The table below is a complete list of the server-side JavaScript functions that adminfs exports:

Server-side JavaScript Examples

• Displaying a property value
• Display all the properties in the headers list. This example uses the RMAGetFirst/Next list enumeration functions.
• Display the HTTPDeliverable list. This is the list of directories that are accessible through Server 8 via HTTP. This example uses the RMAGetNthProperty() to handle the enumeration.
• List Enumeration of Mount Points. This demonstration displays all of the mount points currently in use by the RealServer. This information is found in the registry's FSMounts list in the configuration file, and is reflected in the "config.FSMounts" list in the registry. Each list under FSMounts represents a mount point and its file system plug-in responsible for handling requests for files from that particular mount point.
• List Enumeration of Nested Sub-Lists. This demonstration shows how to enumerate through nested sub-lists in the registry, and to reflect each list's level of nesting, using HTML formatting. This example uses a recursive function to handle the enumeration of each list.

Special Server-Side Tags

The adminfs plug-in recognizes five special tags that perform server-side actions. One tag provides the ability to include another file into the current file; the others provide 'syntactic short cuts' for inserting registry property values into the client-bound HTML. These tags are detailed and demonstrated below.

Use this tag to include another file within the current file. Be careful not to do a recursive include, as this could cause RealServer to crash. This tag is useful for including boilerplate html and/or server-side script libraries in your pages. You must specify the relative path of the included file from the current mount point, regardless of the location of the including file.

Example:

The admin mount point base path is C:\RealServer\RealAdministrator.
Your custom page C:\RealServer\RealAdministrator\custom\mypage.html
includes the file C:\RealServer\RealAdministrator\custom\include\include.html.
The include tag would be <!—INCLUDE file="custom\include\include.html" -->.

As noted earlier, if the adminfs plug-in encounters an error executing the include tag, an error message is inserted into the HTML file sent to the client, in the form of an HTML comment.

Include tag example

The Property Value Tags

<!--$(registry property path)-->

Before sending the page to the client, adminfs replaces this tag with the value of the quoted registry property.

Example:

<!--$(server.ClientCount)-->

<SERVER language="Javascript">RMAOutput(RMAGetPropertyValue("server.ClientCount"));</SERVER>

<SCRIPT>

// example use of escape tag
var logPath = "<!--^(config.LogPath)-->";

</SCRIPT>

parameters.color = "blue"
parameters.size  = "large"

<List Name="MyPropertyList">
   <Var Protocol="TCP"/>
   <Var Timeout="30"/>
</List>

// *** ViewSource *** 
/* 
The following statement creates a new TOCEntry object and saves a (temporary) 
reference to it. This entry is a TOC heading and has no page associated with 
it so the URL parameter is an empty string. Since this heading is a ‘child’ 
of the "Config" heading, a reference to the config TOCEntry object 
is passed as the parent parameter. A key parameter is not passed in since the 
View Source feature is available on all Servers, and is not controlled by the 
Server license. 
*/ 
tmpParent = new TOCEntry( "View Source", "", config ); 

//The next three statements create TOC links as children of the ViewSource heading.
new TOCEntry( "Source Access", "config_viewsrc.html", tmpParent);
new TOCEntry( "Content Access", "config_content_browsing.html", tmpParent );
new TOCEntry( "Browse Content Now", "Javascript:launchHome('browse_content.html')", tmpParent );
/* 
Normally the target window for the URL parameter is assumed to be the 
Administrator’s main or right-hand frame. However, there can be exceptions: since the "Browse Content Now" page 
is designed to be displayed in a separate browser window, the URL to this link 
is a JavaScript function that will open the ‘browse-content.html’ page in a new 
window. 
*/

/* create a subheading in the TOC for the sample pages */ 
tmpParent = new TOCEntry( "Sample Config Pages", "", config );
/* create the links to the sample pages under the new subheading */
new TOCEntry( "Sample 1", "config_sample1.html", tmpParent);
new TOCEntry( "Sample 2", "config_sample2.html", tmpParent);