Open Content Delivery Network (OpenCDN) Project Version: 0.7.7, January 04, 2007 Disclaim: this is not a finite application. It is work in progress material, without any other purpose than test and evaluation. Rights: The oCDN package is released under the terms given in the Perl Artistic License (see http://www.perl.com/pub/a/language/misc/Artistic.html) by their Copyright Holders, which are mentioned in the included AUTHORS file ABOUT ----- The OpenCDN Project is hosted at the University of Roma "La Sapienza", at http://labtel.ing.uniroma1.it/opencdn OpenCDN concerns the development of an application-level Internet Overlay Network, suitable for replication and splitting of Live and recorded multimedia content. Replication of multimedia packets is done by available Streaming Server products from Apple, Real or Microsoft, which turn to be named as "Relays" if cascaded in a multi-hop distribution tree. OpenCDN is written in Perl, and interfaces the Relay technology by a control plane, allowing for remote control of content delivery. When a Relay is wrapped by the OpenCDN control plane, it is termed as an OpenCDN node. Media distribution is hierarchically arranged among participating Nodes, by the aid of a centralised control unit named Request Routing and Distribution Manager (RRDM), also written in Perl. Content providers host their meterial at streaming servers termed Origins, which register at the RRDM the metadata which describe tha available content, letting it to be distributed by OpenCDN. Contents registered to the RRDM are published by a web Portal, where interested Viewers can select a desired program, and start the OpenCDN machinery, which results in the appropriate edge Relay Node to be reported to the Viewer. Communications in between Portal, RRDM, Nodes, and Origins, are performed by XML-RPC calls. Provided that a sufficient number of Relay Nodes are scattered in between the source and the destinations, media can be efficiently distributed to a very large number of clients, without severe network and server requirements, actually performing an Application Level Multicast content routing. In particular, first and last mile will be crossed only once. The code is modular and allows for easy porting to different Relay technologies: active development is based on Darwin Streaming Server by Apple, and Helix Universal server by Real. Use of WM servers should also be possible, by writing a new Adaptation Layer. You can experiment operations by visiting an announcement page, asking for some content, wait for distribution set-up, and pick up content from the nearest node. Also, you can contribute as a content provider, or as a redistribution node. CONTENTS -------- - dirs CPAN - Perl modules in addition to the standard distribution doc - some README files - better documentation will come etc - configuration files html - page from which users ask for a live content, and more +- perl - Perl CGI code which asks RRDM to set up a distribution chain and | which returns a page showing the selected surrogate for the client | (and more) +- images - images used by the Portal and the Content Provider Kit lib - Perl modules used by the applications xpl - RPC::XML methods - files RRDMd.pl - Perl code implementing Request Routing and Distribution Management Node.pm - Perl code which interacts with the Adaptation Layer and the RRDM Origin.pm - Perl code running at contributing sources Install - Bash script for the Installation of distributed code patch.pl - modifies a Darwin script file for proper permissions setting launch.sh - starts RRDM and/or some nodes mk_ipaddr - if you put more test nodes on the same host, more IP address are needed mktgz - creates a distro tarball or a pretty printed file with all the source code reqgen.pl - Generates Requests to RRDM in cyclic fashion oCDN.rc - to be called from rc.local or to run unattended REQUIREMENTS ------------ The code has been tested on the following systems: Linux Red Hat 9 and Fedora Core (1-6), Slackware 8 and 10, Debian Woody and Sarge, Solaris 7 and 8. As Perl (we used version 5.8.0) is portable, chances do exist that the code works with other Unixes also, and with Windows platforms. Operations of nodes is tested on the Darwin Streaming Server 5.5.1 by Apple, and/or Helix Universal Server 9.07 by Real. If desired to use another Relay Servers (e.g. WindowsMedia), a new "Adaptation Layer" has to be written (see doc/README.adaptation). Contributing content providers may use a Quicktime Enconder, or the tools by MPEG4IP, or VideoLAN, or an Helix Producer, or probably much more else, as far as the result can be sourced by Darwin or Helix. INSTALLATION ------------ As a normal user (call it ocdn if you like), unpack this package in a directory (call it $INSTALL_DIR if you like) You should also get a streaming server implementation, and install it, as described in doc/README.Darwin and doc/README.Helix files. Although, you could just run an Origin or an RRDM daemon, or just use a Dummy adaptation layer, and don't need a streaming server at all. Or, you can run a Content Provider Kit, whch is based in VideoLAN, in which case, you should look at README.CPK. Then, the OpenCDN install script included in the distribution must be executed, by running ./Install as root, and specifying which kind of entity(es) you wish to install, i.e. (Dnode | Hnode | rrdm | origin | CPK | all) are respectively for a Darwin node, an Helix node, an RRDM, an Origin, a Content Provider Kit, or everything. At the top of the file, you must change installation parameters, especially if you intend to run a Darwin Node, you must set the user name under which it will run. Re-execution of the install script should be armless. Or, you can manually install OpenCDN, by following the instructions given in doc/README.install, which can be a good thing to do, in the case you are performing installation on an architecture yet unsupported (i.e. which is different from Linux or Solaris). CONFIGURATION ------------- OpenCDN is made by four kind of entities: * a Web Portal where people selects a content, invoke a CGI which asks for OpenCDN configuration, and receive the contact information * an RRDM invoked by the portal, and which performs OpenCDN centralized control * several Nodes which act as Application Level Multicast routers * some Origins which are located at the Content Provider premise Operations of these entities are based on five configuration files, containing Perl Variables initialization, and full comments about the variables meaning and suggested values. /$INSTALL_DIR/etc/CommConf.pm contains values used by RRDM, Nodes, and Origins, so you must edit it anyway, indicating the IP address and port or RRDM (either at your premise, or the public one at 151.100.122.171:4400), and logging preferences. Also, a shared password ($oCDNpassword) must be configured here, in order to activate entities authentication procedures (see doc/README.authentication for details). Such a password must be asked to the RRDM/portal administrator. /$INSTALL_DIR/etc/RRDMconfig.pm contains values only related to RRDM so you can safely ignore it, if you don't run an RRDM. /$INSTALL_DIR/etc/NodeConfig.pm contains values related to the Node control layer; you must specify the Node IP address and port (choose one which is not firewalled) and direct/indirect footprint arrays (see doc/README.routing for a description about how footprint information works). Also, you can configure here whether a Darwin or Helix Streaming server is being used. If you don't run a Node entity, you can refrain form editing this and the following two files. /$INSTALL_DIR/etc/DarwinConfig contains values related to the Apple Darwin Streaming Server; you must follow the instructions given at point 3 of doc/README.Darwin. /$INSTALL_DIR/etc/HelixConfig contains values related to the Helix Universal Server; you must specify your Administrator Username and Password, as chosen at Helix installation. /$INSTALL_DIR/etc/OriginConfig.pm contains metadata information about the Contents to be provided by the OpenCDN, and needs to be edited only by Content providers. These information will be published to the RRDM at the Origin boot time. See also the PARTICIPATION section below, for a more detailed explanation about configuration guidelines. EXECUTION --------- OpenCDN entities can be executed by directly launching either RRDM.pl, Node.pm, or Origin.pm. Try option -h for a list of runtime options, which will override those given by Configuration files. Alternatively, you can use the script ./launch.sh which launches the entities for you, allows to specify some run-time options to be edited on top of the file, and kills stale processes previously started. Also, the script provides a series of options for testing purposes, whose configuration files are present in the CVS, but not in the distribution tarball. Finally, a trivial oCDN.rc script file is given, to be inserted in rc.local, for launching OpenCDN at boot time. OPERATION --------- If you run an RRDM, and an Apache daemon is running, you can access an OpenCDN service request page, located at http:///oCDN/perl/index.pl (upward dirs should be chmod-ed 755) and which looks like the page located at http://labtel.ing.uniroma1.it/oCDN/perl/index.pl, which you should use instead, if you are not running an RRDM. From the OpenCDN service request page you can choose an action and a source. The available contents shown, are that advertised by content providers. After having requested for Service, a new page will report about the best Node from where you should pick up media. You can query about RRDM status, by clicking on the "Status" link given in the top right corner of the OpenCDN service request page, and verify about node registration data, content availability, and distribution setup. From the same pages, you can query about the XML-RPC methods available at the RRDM, Nodes, and Origins. If you want to experiment operations of RRDM and Nodes, without installing the Apple Darwin SS or the Real Helix US, you can use the Dummy adaptation layer, to be configured in etc/NodeConfig.pm. FIREWALL SETUP -------------- In order to properly run one OpenCDN entity, you must take into account the following inbound port usage checklist: Entity | Ports Proto Service Note ----------+---------------------------------------------------------------- RRDM | $rrdm_port TCP XML-RPC communications | $rrdm_port+1 TCP XML-RPC SetUp and Teardown | in forked mode | Node | $node_port TCP XML-RPC communications | $node_port UDP UDP probe requests ! $image_port TCP PYTE probing for LastHop selection | Origin | $origin_port TCP XML-RPC communications | $origin_port UDP UDP probe requests | VideoLAN | 554 TCP RTSP commands | Darwin SS | 554 (default) TCP RTSP commands | 6970 and above UDP RTP and RTCP media packets in & out | (maybe, till 9999) | Helix US | 554 (default) TCP RTSP commands | 34445-34459 UDP RTP replies for UDB resends | 6970 -32000 UDP RDT data chanel in & out | 2220 -2224 TCP,UDP pull splitting requests in & out | 30001-30020 TCP,UDP live data distribution in & out Values of Variables $rrdm_port, $node_port and $origin_port are those given in etc/CommConf.pm, etc/NodeConfig.pm and etc/OriginConfig.pm, which default to 4400, 4404 and 4407 respectively. RTSP ports are configurable in etc/Darwin and etc/Helix; the latter allows also to configure the port numbers for Helix Pull Splitting. PARTICIPATION ------------- This is an Open Source Project, and anyone can contribute to the code development process, to its testing, and to the deployment of a global Delivery Network for live streaming. Please refer to * the TODO file in the distribution for a "left things" list; * doc/README.routing for an overview on how the delivery process works; * doc/README.authentication for XML-RPC authentication of the entities which take part to the same OpenCDN * doc/README.RTSP for inter-nodes delivery authentication; * doc/README.interprocess for inter-entities communication mechanism; * doc/README.adaptation for a very very short overview of the Adaptation Layer API (only if you which to develop a new one). If you intend to partecipate with some entities, be sure to ask to the RRDM adminstrator for the password to be put in $oCDNpassword in etc/CommConf.pm. Then, you can a) run a LastHop node, which will serve your LAN users. It will register itself to the public RRDM, located at 151.100.122.171:4400, and accessed at http://labtel.ing.uniroma1.it/oCDN/. For this, set - in etc/CommConf.pm $rrdm_addr = '151.100.122.171'; $rrdm_port = '4400'; - in etc/NodeConfig.pm @directfp = ( 'your-subnet/mask' ); The FootPrint (FP) information is much like a routing table entry, and identifies the address range you plan to serve directly: if you serve more disjoint subnets, put all of them in the @directfp array, comma separated. The result of this configuration, is that all the clients in your LAN will share an unique inbound stream coming to your LastHop node, without congesting your lastmile connection. b) contribute with new content, either live (such as a street-webcam or a TV broadcast grab) or prerecorded. You must run a streaming server and the Origin.pm daemon, and edit etc/OriginConfig.pm, in order to publish metadata informations about your contents. Also, the value of $RTSPauth_enable must be set in etc/NodeConfig.pm. From Release 0.7.7, OpenCDN provide a Content Provider Kit, which is a sub-distribution of the code base, limited to the Origin entity, which allows the use of VideoLAN as an encoder, and backed by a friendly Web Administration Interface. To follow this route, consult README.CPK c) run a FirstHop Transit node, which will be the root of the distribution for content provided by Origins located in your LAN. It will automagically co-exist with the LastHop node of your LAN, so configuration is the same as for the a) case. Clients within your LAN will receive content provided by Origins you own, directly through this First/Last Hop, while clients outside your direct footprint, will need a LH at their premise, or a public, well connected LastHop node. If you don't want to fill up your outbound link with unnecessary connections, set - in etc/NodeConfig.pm $node_char = 'lazy'; This will hint RRDM to add another Transit relay (if it is available) along the distribution tree rooted at your premise. If you do provide content through an Origin located within your LAN (b case), and miss to place a FirstHop Transit Node, clients in your LAN, which request that content, will see it flowing from the Origin, to the less specific Transit Node found (such as the one depicted in d), and then back to your LastHop node. d) run a Global Transit node, which will be used along the distribution path in between Origins located behind neighboring POPs, FirstHop Nodes if they are present, and LastHop nodes located in remote LANs, where clients are present. Such a Global Transit node will alleviate the load on the first-mile link, coming from Origins and FirstHop nodes. Do this if you are on a well-connected location, and also add a LastHop behavior to your node, in order to provide direct access to clients in the same net. For this, write - in etc/NodeConfig.pm @indirectfp = ( '0.0.0.0/1', '128.0.0.0/1' ); @directfp = ( 'your-subnet/mask' ); $node_char = 'labour'; If more than a Transit node do exist in the same OpenCDN, which announced such a large FootPrint, the Origin or FirstHop will UDP probe them in parallel, and find the nearest, so that each Transit Node will become a relay only for neighboring LANs. Also, you can provide LastHop relaying for clients which are located within neighboring LANs, but haven't placed any LastHop Node which can serve them. For this, write @directfp = ( 'your-subnet/mask', 'LAN1-subnet/mask', 'LAN2-subnet/mask', ... ); When the number of clients attached to your LastHop BackBone Node will grow, their last mile link will congest, making the streaming impossible. It will then be in the interest of user communities, to place a LastHop node serving their own LAN. Finally, you can provide last-resort Global LastHop relaying, for clients located anywhere in the world, and which do miss a LastHop with a suitable, more specific, footprint. For this, write @directfp = ( '0.0.0.0/2', '64.0.0.0/2', '128.0.0.0/2', '192.0.0.0/2', ); More elaborate configurations, will be suggested when OpenCDN begins to grow seriously :-) TROUBLESHOOTING --------------- Q: When I ask for RRDM Status/Node Registration Data, a "No Data" page appears! A: Reading , you can find that the RPC:XML implementation supports compression of requests and responses (if their dimension exceeds a threshold) via the Compress::Zlib module available from CPAN. Maybe the support is not as good as it should: I resolved the problem by simply removing the Compress::Zlib module, by typing rpm -e perl-Compress-Zlib Comments to alef@infocom.uniroma1.it