System Requirements for MVoD Client and MVoD Server

• JDK 1.1.4 or higher

Supported platforms for the RTP DataPump in this release:

• SUN Sparc Solaris 2.6
• SUN Sparc Solaris 2.5.1
• DEC Alpha OSF 4.0
• IBM RS6000 AIX 4.2
• SGI Mips Irix 6.2
• i586 Linux (kernel version 2.30 or higher)

(more platforms may be available upon request)

Installation and configuration instructions:

• You probably already un-tared the tar file since you see this README file.
• You may need to set the environment variable MVOD_HOME to where you installed the mvod package. It defaults to $HOME/mvod so if you un-tared the MVoD-tar file in your HOME directory you don't need to set MVOD_HOME explicitly.
• You may also need to set JAVA_HOME to the directory where JDK 1.1 is installed. The mvod script is trying to figure this out automatically and will tell you if it fails.

Some notes about the directories you see under $MVOD_HOME:

• The sessions directory holds the session information files (*.mvod) for the MVoD Server (pure text files). Please never edit these files by hand!
  
  
• The data directory holds the RTP data recorded by the RTP DataPump. This directory actually depends on the entry in the $MVOD_HOME/.rdcpd_passwd file, see below, so you may configure multiple RTP DataPump users with different data-directories, say data-1, data-2, etc.) Initially one RTP DataPump user with userid "mvod" and directory "./data" is configured. Since the RTP DataPump is always started in the $MVOD_HOME directory when you use the command "$MVOD_HOME/bin/mvod pump" to start it, the relative path ./data means that the default directory for the user "mvod" is then always $MVOD_HOME/mvod/data regardles where $MVOD_HOME is. You will find one session description file (*.rdcp) for every session and two files (*.rec and *.idx) per media in a session in this directory. An index file ends in .idx and a data file ends in .rec. The filenames for these files are automatically generated out of the session filename and the corresponding rdcp-id. For example, given that a session stored in the session file whd-007.rdcp consists of one media with rdcp-id 0 and and one media with rdcp-id 1. Then the automatically generated media files would be: whd-007-0.idx, whd-007-0.rec, whd-007-1.idx and whd-007-1.rec. The content of the .rec file is more or less the raw rtp-data dumped into the file as it was received from the network. The .idx file contains a fixed-length header per data packet which holds a mapped timestamp generated from information of the rtp-timestamps, an offset to the corresponding rtp-data packet in the .rec file and a few other details. If you need more information about the file format, please contact: mvod@pi4.informatik.uni-mannheim.de.
  
  
• The cache directory holds SAP cache entries for the MVoD Server (*.an) and a dump file (*.se) per active session. If the Server is stopped (or killed or crashed...) when sessions are active (e.g. playing, recording or scheduled for playing or recording), all active sessions will still survive as dump files in the cache directory. By default, the server reads all these dumped *.se files when it starts and tries to recover all the sessions in the state they where left when the server was stopped. This behaviour can be omitted when the server is started with the option "-r", which will not restart any session but leave the dumped session files in the cache directory). To clean all cached sessions start the server with the option "-s". To clean cached announcements and to force the server to receive all SAP announcements from scratch, start the server with the option "-a".

MVoD Server configuration

• .mvod (the general MVoD configuration file)
• .mvodap (the setup file for the MVoD Announcement Protocol)
• .mvod_passwd (user file for the MVoD Server)
• .mvod_groups (groups file for the MVoD Server)
• .sap (the setup file for the Session Announcement Protocol)

Therefore we recommend that you always use the MVoD administration tool (start it with "$MVOD_HOME/bin/mvod admin") to customize and administrate the MVoD Service through a GUI.
You need to start the MVoD Server first (see below) in order to run the MVoD administration tool. Note that the administration tool only provides a graphical user interface and accesses the MVoD Server through RMI to actually do all the configuration.
Most of the parameter changes even take immediate effect even when the server is running. E.g. you can add/remove users, change guest_login_allowed, etc. during runtime. Changes that you make in the configuration files by hand are not only discouraged but will also not be available until you restart the server by hand.
To be able to login to the MVod Server with the admisitration tool, a user must be a member of the special group "admin". A special user "admin" with group "admin" is configured allready in this distribution and must always be present. This user may be used to administrate the MVoD Service. Initially the password for the user admin is "admin". Please change this password immediatly after login with the administration tool so that no one else has access to your MVoD Server with this default password!

RTP DataPump daemon configuration

The syntax is as in a unix /etc/passwd file, use "mvod pump -admin" to manage the content of this file).

Initially a user "mvod" with password "only4mvod" is configured for the MVoD Server to access the RTP DataPump Daemon. You will find these values in the $MVOD_HOME/.mvod file also. The $MVOD_HOME/.rdcpd_passwd file must either be in the directory from where the RTP DataPump daemon is started or specified as command line parameter on startup. This is done automatically if you use the command "$MVOD_HOME/bin/mvod pump" to start the RTP DataPump. See section data-directory above for some comments on how the data-directory is used. The MVoD Server contacts the RTP DataPump daemon through the RTP DataPump Control Protocol (RDCP) when it starts up and asks information about all recorded sessions. Also a new RDCP connection is establised for each newly created or opened sessions. For each RDCP connection, a new process with a new RTP DataPump is forked by the RTP DataPump daemon. If an RTP DataPump is killed when a session is active, the MVoD Server will always try to recover (i.e. it tries to call the RTP DataPump daemon again to create a new RTP DataPump and tries to recover the session in the state it was before the RTP DataPump went down). If you kill the RTP DataPump daemon, all sub-processes created by the daemon will also be killed.

Default user

To start the MVoD Service

• You will find a shell script "mvod" in the directory $MVOD_HOME/bin that will do most of the work for you... If you start it without a parameter you will get a short help screen.



• On the host where you want to run the MVoD Server you first have to start the RMI registry. You can do this by running the command: "$MVOD_HOME/bin/mvod reg [<rmi_port>]". The specification of a portnumber is optional, the default port is 1099. If you allready have rmiregistry running on your system because other people/projects use it as well, this command will fail and you will have to kill the allready running rmiregistry and either restart it with the above command or start it by hand and add the string: "$MVOD_HOME/bin/mvod-admin.jar" to the environment variable CLASSPATH beforehand. If you do not specify the correct CLASSPATH, the MVoD Server will fail when you try to start it with with an error messages like that:

  Unexpected exception; nested exception is: 
          java.lang.ClassNotFoundException: mvod.admintool.AdminServer_Stub
  

  
  If your RMI registry is listening on a different port than the default you may specify the port with the "-p <rmi_port>". The RMI registry is needed to be able to access the MVoD Server with the administartion tool. If you do not want to access the MVoD server with the MVoD Administration Tool, you may skip this step and start the MVoD Server (see below) with the option "-n". However, be aware that in this case you may not change any of the configuration parameters during runtime.



• On the host where you want to run the RTP DataPump daemon (typically but not necessarily the same host where you will start the MVoD Server) run the command "$MVOD_HOME/bin/mvod pump". Make sure that the MVoD Server can access the RTP DataPump daemon with the data_pump_host, data_pump_userid and data_pump_password specified in the $MVOD_HOME/.mvod configuration file, otherwise you will get a "Connection refused" or "Login incorrect" message from the RTP DataPump when you start the MVoD Server (see below).



• Now you can start the MVoD Server by running the command "$MVOD_HOME/bin/mvod server". If log_level is set in $MVOD_HOME/.mvod the server will create a log file as specified with log_file in $MVOD_HOME/.mvod where all activities according to log_level will be logged. You may always trace the servers activity with "tail -f <log_file>".



• Finally you can start an MVoD Client on any host by running the command: "$MVOD_HOME/bin/mvod client".



• You can now also start an MVoD Administration Tool on any host by running the command: "$MVOD_HOME/bin/mvod admin". You can specify the hostname of the host where the MVoD Server is running on the command line (or in the login window) when you want to administrate a server on a different host than the one where the admin tool is running. You may also specify a portnumber in case the rmiregistry is running on a different port as the default (default is 1099).

A typical example would look like this

whd@solon [~/mvod] > ./bin/mvod reg
... RMI Registry will be started in the background, some messages appear...

whd@solon [~/mvod] > ./bin/mvod pump
... RTP DataPump daemon will be started in the background, some messages appear...

whd@solon [~/mvod] > ./bin/mvod server
... MVoD Server will be started in the background, some messages appear...

whd@solon [~/mvod] > ./bin/mvod client

... and we are (well, should be) ready to go for a first test... (yes all MVoD components can be started on the same host, this is no problem for playbacks, however, you might not be able to record any data from MBone tools running on the same host, see below under general comments)

... and a little later, you might remember that the README said please immediatly change the passwords for the users "mvod" and "admin" and the RTP DataPump password so you now might want to start the administration tool with:

whd@solon [~/mvod] > ./bin/mvod admin

... and do the necessary changes in the MVoD Server configuration. The command "mvod admin" can always be started, however, to connect to an MVoD Server for configuration, RMI registry and an MVoD Server must be running. Afterwards, you start the command:

whd@solon [~/mvod] > ./bin/mvod pump -admin

... to do the necessary changes in the RTP DataPump configuration as well. The command "mvod pump -admin" can always be started, regardless whether an RTP DataPump daemon is running or not. Changes in the .rdcp_passwd file will always be immediatly available to a running RTP DataPump daemon.

The advanced user may start reg, pump and server in a row with:

whd@solon [~/mvod] > ./bin/mvod all

However, in this case you may not give any commandline options to the RTP DataPump or the MVoD Server.

To stop the background processes of the MVoD Service (reg, pump and server), you may use the commands:

whd@solon [~/mvod] > ./bin/mvod kill reg
whd@solon [~/mvod] > ./bin/mvod kill pump
whd@solon [~/mvod] > ./bin/mvod kill server

The advanced user may stop reg, pump and server in a row with the command:

whd@solon [~/mvod] > ./bin/mvod kill all

or even with:

whd@solon [~/mvod] > ./bin/mvod kill -f all

MVoD Client as Applet

• to install the MVoD Client as an applet, you need to add the following lines of code to your html-page:

  <applet
   code="mvod.client.MvodApplet.class"
   archive="mvod-applet.jar"
   width=76
   height=64>
   <param name="MVoDServer" value="idl:sunw.door://name-of-your-mvod-server-host:4465/MVoDServer">
  </applet>
  

  and change name-of-your-mvod-server-host to the hostname of your MVoD Server (for applet security reasons, this must be the same host as your web server, so the MVoD Server must be started on this host!)

• Copy the file: mvod-applet.jar into the the directory where your html file is stored.

• Create a subdirectory "gif" in this directory and copy all the gif files from the mvod distribution into it.

• That's basically it. Note that most of the Browsers do not fully support JDK1.1.4 and therefore you might see some ClassNotFoundException... To verify the applet installation, please use the appletviewer, this is know to work. If this doesn't work you probably misconfigured something (if you get a SecurityException, you may have to loose the security restrictions in the appletviewer). If it works with the appletviewer and not with your browser, it is very likely that your browser is not fully JDK1.1.4 compatible.

• Browsers known to work:
  • Appletviever (jdk 1.1.4 or higher)
  • HotJava (1.0 or higher)
  • Netscape Communicator (4.04 with jdk1.1.4 patch). The patch is available at: http://developer.netscape.com/library/documentation/communicator/javajdk.html

  Please let me know if you have succesfully tested it with any other browser or on any other platform so I can add it to the list of supported browsers.

MVoD Client usage

Some general comments:

• If the MVoD client does not see the server announcements (i.e. the server doesn't appear in the list on the gui of the client when the client starts, client and server may not have multicast connection or the TTL for the server announcements may not be set high enough (see .mvodap).



• Note: With most of the MBone tools, you cannot record data that is sent from the same host where the RTP DataPump daemon is running (e.g. with vat, vic) because these tools do not do so called local loopback. However, for playback you can run the RTP DataPump daemon and the MBone tools on the same host since the RTP DataPump does not turn off local loopback.



• The MVoD Service currently only supports RTPv2 data streams. Other streams like the ones generated by wb or nt are not supported. If you connect to a session that consists one or more unsupported streams, these streams will be silently ignored.



• We experienced problems when the RTP DataPump runs on one machine and stores or reads its data from an NFS drive on another machine. Therefore we suggest to avoid such situations.



• Probably not necessary to say but just to complete things, the MVoD Client can not playback any RTP data streams. To playback the data streams received by the RTP DataPump you have to start some RTP compatible tool e.g. vat for audio and vic for video. This can, however, be easily done from within the MVoD Client in the tools menu.

If you have any comments, please send us your feedback to mvod@pi4.informatik.uni-mannheim.de

Thanks.
-- Wieland

Very special thanks for their help/support/jokes/hacks/bugs/bug-fixes/etc. that contributed tremendously to the project goes to:

• Achim Steinacker (now Technical University of Darmstadt) - the MVoD Server guy
• Markus Kaas (now SAP AG Walldorf) - the 1. MVoD Client guy
• Michael Grundel (University of Mannheim) - the 2. MVoD Client guy
• Reinhard Kirchner (University of Mannheim) - the Admin Tool guy
• Christian Bartolomae (University of Mannheim) - the Local-Client guy
• Mattias Mattsson (ICAST Corp.) - the plumber (working hard with the pump)
  
• and many others... (let me know if you think you are missing on the list :)