Policy File Server Service

Overview

The Policy File Server Service (implemented by the class org.moock.unity.opt.policyserver.PolicyServer), is a server for sending policy files to Macromedia Flash in response to Flash's System.security.loadPolicyFile() method. Using loadPolicyFile(), movies running in Flash Player 7.0.19.0 or higher can retrieve a "policy file" that describes the domains and ports over which Flash clients can connect to Unity 2 Multiuser Server. In particular, a policy file can allow:

connections to Unity 2 Multiuser Server from different domains
connections to Unity 2 Multiuser Server on ports below 1024

Note that Unity 2's Policy File Server Service works only with movies running Flash Player 7.0.19.0 or higher.

Deploying the Policy File Server Service

To add the Policy File Server Service to your installation of Unity 2.0 Multiuser Server, follow these steps.

Step 1

In the root of your Unity installation directory, edit uconfig.xml. Under the existing <SERVER> tag, add a <SERVICE> tag with the following structure:

<SERVICE>
    <ID>PolicyFileService</ID>
    <CLASSNAME>org.moock.unity.opt.policyserver.PolicyServer</CLASSNAME>
    <ATTRIBUTES>
        <PORT>9102</PORT>
        <POLICY_FILE>policy.xml</POLICY_FILE>
    </ATTRIBUTES>
</SERVICE>

In the above <SERVICE> tag:

ID is the Service name, used primarily to refer to the Service in logs
CLASSNAME is the Java class for the Service
PORT is the port on which the Server will listen for policy file requests
POLICY_FILE is the policy file to be sent (an example policy file is shown below, and included with the Unity 2 Multiuser Server installation)

Step 2

Add unity_optional.jar to the CLASSPATH in the startup script you use to start Unity 2 Multiuser Server (startserver.bat or startserver.sh).

Example: java -cp lib\unity_optional.jar;lib\xerces.jar;lib\unity_core.jar;lib\log4j.jar;lib\jdom.jar -Dlog4j.configuration=file:ss.lcf org.moock.unity.core.Unity start

Step 3

Create a policy.xml file in the location specified above, according to the structure described below. (Note that Unity 2 Multiuser Server ships with an example policy.xml file.)

Policy File Structure and Delivery

A policy file takes the following structure:

<cross-domain-policy>
<allow-access-from domain="hostname_or_ip" to-ports="port_list"/>
</cross-domain-policy>

where hostname_or_ip specifies domains that may connect to the server, and port_list specifies ports to which Flash clients are allowed to connect. Multple <allow-access-from> tags are permitted, as are wildcards, multiple ports (n1, n2, n3), or port ranges (n-n1). The following policy file demonstrates various ways of formatting an <allow-access-from> tag:

<cross-domain-policy>
  <allow-access-from domain="*" to-ports="507" />
  <allow-access-from domain="*.foo.com" to-ports="507,516" />
  <allow-access-from domain="*.bar.com" to-ports="516-523" />
  <allow-access-from domain="www.foo.com" to-ports="507,516-523" />
  <allow-access-from domain="www.bar.com" to-ports="*" />
</cross-domain-policy>

Note that the Flash Player can only connect to a port under 1024 if the policy file itself is served over a port under 1024.

Unity's Policy File Server reads the policy.xml file from disk each time it is requested. Hence, it is possible to change the contents of the policy.xml file at runtime, without restarting Unity.

The Flash Player will not retrieve policy files over any of the following ports:

22 (SSH)
25 (SMTP)
37 (time)
43 (WHOIS)
53 (DNS)
88 (kerberos)
111 (portmap)
113 (ident)
137-139 (windows networking)
143 (IMAP)
161-162 (SNMP)
389 (LDAP)
465 (SMTPS)
500 (ISAKMP)
535 (IIOP)
546-547 (DHCP)
636 (LDAPS)
749-754 (kerberos 4)

For information on connecting to a policy file with UClient for Macromedia Flash, see the UClient constructor and UClient.setServer() method in the uClientCore API documentation.

Testing the Policy File Server

To test both Unity 2 Multiuser Server and the Policy File Server, it is possible to telnet to the ports on which they are running. After a successful connection to Unity 2 Multiuser Server, an XML tag containing a client id is returned. After a successful connection to the Policy File Server, a policy file is returned. If either server does not return any content after connection, it is not running correctly. See the server log for troubleshooting help. If both servers return the expected content, but a Flash movie cannot connect, then the movie is not configured correctly or the Flash Player version is too old (i.e., prior to version 7.0.19.0). See the client-side log for troubleshooting help.

For more information on Macromedia Flash policy files, see Macromedia's Flash Player 7 Release Notes.