How to run a Bridge Server

 

Futures Laboratory

Argonne National Laboratory

9700 S. Cass Ave.

Argonne, IL 60439

 

1.    Introduction

Version 2.1 of the Access Grid Toolkit included a bridge server to integrate multicast/unicast bridging with virtual venues. 

 

This document describes how to run a bridge server.

2.    Overview

Given a venue or list of venues, the bridge server will:

  • retrieve the list of multicast addresses in use
  • allocate a port on the local machine for unicast traffic
  • execute QuickBridge to begin bridging the multicast traffic to the unicast port
  • register itself with the venue(s), so that users can select it

 

The BridgeServer listens for the addition of new multicast addresses to a venue, and will create new bridges for them.

 

If a venue becomes unreachable, the associated QuickBridge processes will be terminated.  The BridgeServer will continue to try to contact the venue; if it succeeds, it will reconnect and start the QuickBridge processes again.

 

Further details of the BridgeServer are available in the BridgeServer design document [1].

3.    Running the Bridge Server

3.1.          Create a BridgeServer configuration file

The BridgeServer must be pointed at a venue or venues at startup.  To this end, the BridgeServer includes options for specifying the venue or venues to bridge.

 

The BridgeServer also includes options for specifying the name and location of the provider of the bridge; this allows users to select the site to which they wish to bridge on a name/location basis. 

 

Options are specified in a configuration file; the format of the configuration file is as follows (note that the configuration file format differs by release):

 

 

Text Box: [BridgeServer] # the “id” field is assigned by the system; users can omit this line id = <unique id of this bridge server> name = <name of your institution, without spaces > location = <location of your institution, without spaces > qbexec = /usr/bin/QuickBridge # ONE of the following mutually exclusive options can be specified venue = <URL of venue to bridge> venueFile = <file containing URLs of venues to bridge> venueServer = <URL of venue server to bridge> venueServerFile = <file containing URLs of venue servers to bridge>

Format of BridgeServer configuration file (AGTk 2.1)

 

 

Text Box: [BridgeServer] # the “id” field is assigned by the system; users can omit this line id = <unique id of this bridge server, without spaces> name = <name of your institution> location = <location of your institution, without spaces> qbexec = /usr/bin/QuickBridge # optional specification of port range for all bridges portMin = 30000 portMax = 40000 # any number of Venue and/or VenueServer entries in the following format [https://myvenueserver:myport/Venues/000000f5569d4ffc008c00dd000b00377de] type = Venue # optional specification of port range for bridges in this venue portMin = 30000 portMax = 30010 [https://myvenueserver:myport/VenueServer] type = VenueServer

Format of BridgeServer configuration file (AGTk 2.2, 2.3)

 

3.2.          Execute the BridgeServer

To run the bridge server, execute the following command:

 

BridgeServer.py –c <configFile>

 

The BridgeServer will display gobs of text to the window, including BridgeServer output:

 

Bridging venue: https://localhost:8000/Venues/default

 

and output from the running QuickBridge processes:

 

max_unicast_mem is 32

myhostname=munich

myhostipaddress=127.0.0.1

 

using multicast

ucport[data]=50694  ucport[rtcp]=50695

mcport[data]=2002  mcport[rtcp]=2003

making multicast port[0]

making multicast port[1]

No bridge.acl file found, no ACL set

 

This output is (currently) not captured anywhere.  The BridgeServer does, however, generate a log file in UserConfigDir/BridgeServer.log.  This log includes information about which venues are being bridged and the ports being used.

3.3.          Using the Bridge

From within the venue client, on the Preferences menu, select the “Use Unicast” option.  The dialog below will be displayed, from which a bridge can be selected.  Press OK, and the media tools will be restarted to point at the bridged addresses.

 

 

 

 

3.4.          Terminating the BridgeServer

To stop the BridgeServer, press Ctrl-C in the window where it was started.  The BridgeServer will shut down its running QuickBridge processes.  The associated bridge entries will be removed from the Venue automatically (internally by the Venue).

4.    Troubleshooting

 

  • The “Use Unicast” option in the venue client will not be selectable if a bridge server is not being run against the venue.  (This is technically a venue client issue, but is mentioned here for your convenience.)

  • When bridging an entire venue server, the BridgeServer will bridge the venues configured at the time it is run.  Venues added to the venue server thereafter will not be automatically added to the bridge.

 

  • A BridgeServer should not be run on the same machine as a venue client that will try to enter the venue(s) being bridged.  Both processes will attempt to use the same port, and the second process will be denied access.

 

  • If a BridgeServer is not providing bridges for all the streams in a venue, an error message will be displayed to users who select the bridgeserver from the list, and the media tools will revert to their previous values (whether multicast or some other bridge).

 

  • The BridgeServer in the 2.1.2 release will not run properly against a pre-2.1.2 VenueServer or Venues.  For a pre-2.1.2 VenueServer, use a pre-2.1.2 BridgeServer. 

5.    References

 

  1. BridgeServer Design Document

http://fl-cvs.mcs.anl.gov/viewcvs/viewcvs.cgi/AccessGrid/doc/BridgeServerDesign.doc