This is a working document updated by the Metcast group. This is a step by step procedure to install the Metcast server. The Metcast system is composed of the Metcast server and the decoders, but this document only applies to the server. Database installation is not covered here.

Overview and key terms

Database Servers

This document does not cover database installation or configuration.

The proxy

The proxy does the communication between the Apache fastcgi module and and instance of the Metcast server. It is a short C program. All requests to the Metcast server must pass through this proxy.

A port number (e.g. 3926) is an essential parameter for the proxy. It is used to start an instance of the Metcast server. It can be specified through the environment variable MSERVER_PIPE.

If you do not have a binary version of the proxy, you can compile it using the fastcgi development kit (devkit).

The Metcast server

The file start_server.sh

This file sets various environment variables and starts an instance of the Metcast server. This is the proxy that indirectly starts an instance. The name should be specified in the file inetd.conf. The file contains several environment variables that must be set properly by the installer. Consult it for further details.

inetd or xinetd

/etc/services should specify the same tcp port as the proxy uses (specified in start_server_fcgi_proxy).

Log files

Installation Step by step.

• Database
  • Make sure the needed database servers have been installed, are adequately populated and are working. The installations of these are not covered in this document.
• Apache
  • Install Apache with the fastcgi module.
  • Verify that the Apache server can be started and stopped without error messages in its log file. (The Apache error log file is `error_log' under the logs sub-directory of the Apache root directory; for example /usr/local/apache/logs/error_log).
  • Stop the Apache server for the rest of the installation.
• Metcast
  • Get the appropriate Metcast system. You should have either:
    • A tar file containing at least the sub-directories server and scheme-common. This can be obtained with `cvs export' and using tar on the result, or a tar copy of an already-installed Metcast server.
  • The proxy is started by the Apache server. The name of the executable or the script is specified in the file httpd.conf (see below).The file start_server_fcgi_proxy is a script that can be used to start the proxy. It mainly setups some environment variables for the proxy it do an exec on it. The FastCgiConfig directive, in httpd.conf (see below), can also be used to specify the environment of the proxy.
    • The proxy may or may not reside on the same computer as the Metcast server code. But it resides on the same computer as the Apache server.
    • If you are installing from a tar file, you may need to compile the proxy. This is mainly the compilation of server_fcgi_proxy.c (with sub-compilation of sys_open.c). Consult the source file server_fcgi_proxy.c to get a Unix command line to compile them. You must have the fastcgi devkit installed, in particular the files libfcgi.a, fcgiapp.h and fcgi_config.h. Call the proxy from a Unix shell to see that it is at least compiled.
  • Adapt the file start_server.sh. Many shell variables have to be properly set in that script. It should be well-commented to guide you.
  • Configure inetd or xinetd for metcast.
    • The pertinent line in /etc/inetd.conf taken from Ruby. This specificies the name of the Metcast server (not the proxy).

      mclds   stream tcp nowait web /h/mcsrvr/fcgi-bin/server /h/mcsrvr/fcgi-bin/server
      

    • To configure xinetd for metcast, place a file called metcast in /etc/xinetd.d with these contents:

              # default: on
              # description: metcast server
              service metcast
              {
                      socket_type     = stream
                      wait            = no
                      user            = nobody
                      server          = /h/mcsrvr/fcgi-bin/server
                      disable         = no
              }
      

    • /h/mcsrvr/fcgi-bin/server is a symlink to start_server.sh.
  • Adapt the configuration file of Apache, namely the file httpd.conf (present under the subdirectory conf of the root directory of your Apache installation).
    • The proxy binary should be listed as a fastcgi. This is done in the following way.

      <Location /cgi-bin/mcsrvr/server>
       SetHandler fastcgi-script
       #perhaps other authorization directives
      </Location>
      

    • In that example, the relative path /cgi-bin/mcsrvr contains the proxy named server. It could be a symbolic link to server_fcgi_proxy.
    • The directive FastCgiConfig must be specified somewhere in that file. Here is an example of this directive

      FastCgiConfig -restart -restart-delay 5 -idle-timeout 120 -maxProcesses 30 -initial-env MSERVER_PIPE=tcp://mcdatabase:3926 -maxClassProcesses 30   
      

    • Note that the listen port is directly listed on this directive. This is another approach that avoids using start_server_fcgi_proxy.
  • Start Apache. The fastcgi Metcast server should be ready to use. Note: you will not see any proxy or Scheme file running. A request must be done to start any proxy.
  • Quick Testing. (starting the Metcast server)
    • The Apache must be running. If some of the code files were modified, you should have stop and restarted to the Apache server. (This should stop all running proxies and old Metcast instances.)
    • A browser can be used to test if the fastcgi Metcast server is alive and responding. Specifying URL http://localhost/cgi-bin/start_server_fcgi_proxy should do a get, and the server should answer with an error message that it cannot handled such a request.
    • The script server-emul.sh can be used to further test the server code by providing an environment and a MBL request. See the file test-fastcgi-msl for an example of environment and MBL request.
    • Check the fastcgi log files in the sub-directory specified in start_server.sh to see if the requests went through without problems. Check also the Apache log file for any apparent errors.