Projects - rcbridge

The rcbridge application is designed to allow one (or more, with rcb-forward) machines on multicast disabled/problematic networks to effectively receive and send multicast packets. This is achieved by running the rcbridge application on a machine that is connected to a multicast enabled network and creating a pseudo-tunnel to the local network. While this kind of bridge already exists in several forms, rcbridge has a Remote Control mechanism, and a more flexible forwarding model. This provides much greater flexibility to clients, and puts much less pressure on the rcbridge host since they don't need to manually reconfigure their bridge all the time.

rcbridge also allows (for rtp-based streams) for individual stream selection across the pseudo-tunnel, which makes it very useful for the multicast- AND bandwidth-challenged. One can select an individual stream, or any subset, or all streams, and dynamically change the selection at any time. This is especially useful for people on narrow links, at home (behind an ISP), on wireless links, or on thin devices like PDAs.

rcbridge supports almost any number of downstream clients, up to a theoretical maximum around 64k. The probability of port collisions, and CPU/memory requirements reduce that number, but hopefully even "only" a few hundred clients say would be sufficient in most environments. We would be interested to hear of performance test results.

Client User Interface

Clients can remotely connect to the rcbridge process via a web page that is dynamically created by the rcbridge application. http requests to rcbridge can also be done through other http-literate programs. The rcbridge server runs on a specified port (9090 by default), and new client connections are automatically redirected to a dedicated thread on a different port.

The initial http request to rcbridge allows the client to create a tunnel. Subsequent web forms allow the client to configure the tunnel to their choosing.

M/C Address and Port: multicast address and port to listen/send to.

Time Remaining:
For various safety reasons, any bridge will time-out and close after a certain number of minutes. This field allows a client to see how many minutes they have remaining before a timeout and also to change this value. This value may be changed while bridging without affecting the bridge's connections. The rcbridge configuration defines an upper limit to this number (see below).

Bridge Type:
Set to either Rtp/Rtcp Specific or General Multicast.

If set to "General Multicast", any valid multicast group on any port can be joined. If a client joins a group on an even port packets will be sent back to the client on an even port and if a client joins a group on an odd port packets will be sent back to the client on an odd port. All multicast packets will automatically be forwarded in both directions.

If set to "Rtp/Rtcp Specific" the client enters the group and rtp (even) port to join. In addition to the RTP bridge on the even port, an RTCP bridge is also automatically created on the next odd port. Additionally, in this mode, the client is given the ability to include or exclude selected source streams based on the RTP Source ID.

Once the tunnel is created, the header of the page looks like this:

Connect To:
indicates the address you should point your unicast client at.

Note that by default rcbridge will only create a tunnel to the IP address that the http request came from. There are enough DoS tools out there, we don't need to provide another one :-) This however has implications in some scenarios, e.g. behind NAT devices, or for systems that can't run a web client.

As of v1.1 there is some initial limited support to create a tunnel to a third party address. This is outlined in the configuration section below. Note that rcb-forward may also be an appropriate tool there, although it also has some limitations.

Close Bridges
Clicking on this will tear down the bridges and clear all of the state for your tunnels. You can then enter a new set of parameters.

The following are only available for rtp/rtcp specific bridges

Auto forward all new RTP source streams:
When on, any new rtp stream detected will automatically be selected for forwarding to the client. However this only applies to new streams. Any stream that has already been detected will not change its forwarding state.

Refresh Streams:
The rcbridge web page reloads itself every minute (default value, configurable), and gradually builds a list of sources it has seen. If a source goes away, it is NOT aged out, as it might come back. Hence, you may wish to completely refresh the source cache to remove dead sources, or to see if a new source has appeared since the last page-reload. Note that this will wipe the forwarding state of all streams, so only use it if really necessary.

Select all, Select none:
As the names suggest, these will select or clear all of the available streams, immediately.

The Source Table:

Click for full size image

Note that if you specify an rtp-type bridge for a generic (non-rtp) multicast stream, the rcbridge will show you a source table with hundreds of sources, all at zero (or near zero) bandwidth, as it "detects" random SSRC ID's in all of the incoming packets. You have been warned.

On this table you can select any and all streams you wish forwarded on. The table will grow and fill out (at each refresh) as additional sources are seen, and as rtcp information is received. At the very bottom of the table you will find:

Update Stream Selection:
Clicking the check boxes next to a stream will not automatically forward it to you. Clicking the Update selection button will submit the list of streams that you want to be forwarded to you.

There is also a short summary of the total bandwidth (kb/s) that would be used if you selected all the streams, and the bandwidth sum of the streams that you have selected for forwarding. This currently only updates whenever the page updates.

URL encoded tunnel creation

The initial http GET request to the rcbridge can contain additional data that will auto configure bridges without the need to fill in forms. In the URL the client can specify a multicast address + port to connect to, turn auto-forwarding on, and potentially point the tunnel at a 3rd party target.

http://rcbridge-ipaddr:port/addr=mc-address&port=port&autoforward&target=ip-addr

This mechanism is used by e.g. rcb-forward. Note that the target field is only considered if permitted by the server configuration (see below) and has additional limitations.

Tunneling protocol

Under the current version of rcbridge, the tunneling is done extremely simplistically - basically by taking the payload off the multicast packet and putting it into a new unicast packet for unicast delivery to the client. This means that originator-IP-address information is lost in both directions, and the rcbridge appears to be the source. However, for rtp-based streams, this is not yet a critical issue, as the associated rtcp data (which SHOULD be transmitted by sources) provides the lost information.

The benefit of this approach is that absolutely nothing is needed on the client side, which makes it reasonably friendly for novice users. The client just needs to point their application at the unicast address/port identified by rcbridge

For general multicast-forwarding requirements though, we are considering several options for more appropriate tunneling, such as IP-in-IP, GRE, UMTP, etc. If time permits, or somebody gives us the code, several could be supported and be user-selectable through the web form.

How to install and run the server:

You can download the Java jar and associated files here:

Note that this code is released (c)ANU Internet Futures, 2003-2006. No warranties implied, you take this code AS IS. Use at your own risk

This project is moving to sourceforge. In the meantime, the latest version is available via this interim webpage

The material below is here for descriptive and historical purposes only

The application was compiled against JDK 1.4.1-02 and uses classes that are not available before Java 1.4. We have found that the current JVM-1.4 for FreeBSD is extremely buggy, and does not work properly.

The main method is in the class called RCBridgeMain. It uses several other libraries - all are either standard packages from Java or are part of the anuif2 package included.

The tar file has the following structure:

rcbridge.tar
   |
   +---RcBridge.jar
   |
   +---config
   |     |
   |     +---config.txt
   |     |
   |     +---addrs.txt
   |
   +---html
         |
         +---RedirectResponse.txt
         |
         +---RtpSourceTable.txt
         |
         +---UpdateResponse.txt

Unpack the tarfile into some convenient directory. To run the application from the jar file type:

java -cp RcBridge.jar RcBridgeMain [options]

(noting that the capitalisation of the class name is important), where the [options] include

 --help   | -h                       show help and exit
 --config | -c    [file]             file that contains application data
 --addr   | -a    [file]             file that contains allow/deny addresses
 --mode   | -m    [devel|suppress|release]  increase/decrease number of console messages

You must specify both a 'config' file and an 'addr' file for the application to run.

The config-file contains the parameters needed to setup the server (such as port numbers, buffer sizes, ttl, etc) and run the application. The format of the config file is as follows

[name]=[value]

Note there is no white space before or after the '=' sign. Lines beginning with a '#' sign are ignored. If the params file contains an invalid value or doesn't contain an entry for a required variable the application will notify you as to which variable(s) is/are missing and/or invalid and exit. The tar file contains a sample called 'config.txt'. It is in the 'config' directory.

The 'addr' or ACL-file (access control lists) contains lists of IP addresses that will be allowed or denied connections to rcbridge. Simply list the allowed addresses after the line 'allow' and list the disallowed addresses after the line 'disallow'. To specify an entire domain or subnet use '*' as a wildcard. For example:

allow
150.203.*.*
deny
150.203.1.1
dummymachine.anu.edu.au

This will allow any machine from the main ANU network to connect, except for the 2 machines specified. The tar file contains a sample called addrs.txt. It is in the 'config' directory.

As of v1.1, it is possible to create 3rd-party targeted tunnels, i.e. not back to the requesting http client. However, for obvious security reasons, it is limited. It can only be done by an address explicitly allowed to do so in the 'addr' file, by putting '+' after the address (i.e. '150.203.1.1+'). It can also only be sent to an address within the same 8-bit-level subnet as the requester, i.e '150.203.1.1+' allows a tunnel to be created by 150.203.1.1 to anyone in 150.203.1.*.

This approach is mainly to test if this capability helps some applications, e.g. behind NATs or using appliances like vBricks. The user-interface/protocol to achieve this is likely to change, as we think (or hear) of better ways to do it. Suggestions always welcome.

The 'mode' indicates the level of logging messages to console (default is release)

	release - prints only info and error messages (but doesn't trace errors)
	devel - prints all warning, error, debug and info messages and traces errors
	suppress - no output from our classes; some core java classes may still print.

There is also a 'html' directory containing 3 '.txt' files that are the templates for the generated html pages. The application is hard-coded to look in this directory for these files. However it is possible to change the look of the generated html by modifying these files (just don't change their names or places).

Feedback

We are looking for feedback on rcbridge and how to make it more useful to users. You can email us with comments.

Associated projects

rcbridge delivers multicast content to your subnet over a unicast link. For a single machine receiving that content, this is sufficient. But what if you have several machines on your subnet all wanting the same content? Or what if your client machine can't run a web browser? Use rcb-forward - it's a java client you can run from the command line, it establishes a link to an rcbridge on your behalf (no web browser needed), automatically remulticasts the inbound traffic on your local subnet (and beyond), and forwards your outbound multicast traffic to rcbridge.

Wishlist/Plans

In no particular order

  - Predefined list of addresses presented in the UI, e.g. AG venue list, or SDP announcements
  - Session management that doesn't use ports (e.g. cookies or url-encoded IDs)
  - Ability to support multiple tunnels within a single session/browser
  - use of javascript to update UI/state without requiring full page refresh
  - tunnel protocols (which also impacts the client end)
  - a system for registration of rcbridges, and sensible/automatic detection of "near-by" rcbridge services
  - extension into more general application-layer multicast environments
  - possibly move away from Java
  - integration with directory services to support AAA mechanisms for access to multicast sessions
  - support for the RTP MIB (and any other relevant MIBs)
  - administrative interface (see clients/selections, administer ACL, etc.)
  - ability to securely setup 3rd-party-targeted tunnels
  - support for SSM

Known issues

  - Meeting point functionality has not been well tested. If your network configuration happens to forward your outbound packets back to your own interface, it will work fine as a meeting point.
  - The Mozilla browser engine (used in various browsers) has some odd, irregular and inconsistent behaviour with html forms generated by rcbridge if the POST method is used for the form action. We'd be grateful if anybody can track this down. In the meantime we have set rcbridge to use GET by default (set in the config file).