CINEMA Installation Manual


Installation from Sources

    Please see the file README.build in the CINEMA top-level source directory for instructions on building the sources. Platform specific instructions are in platform directories. For example, for building the sources on Windows 95/98/NT/2000, please see the file NT/README.win32. Once the binaries have been built, proceed with the instructions for binaries, below.

Installation using Binaries on Unix

  1. Install the mySQL database server from binaries or sources. We use version 3.23.37, although any version 3.23.33 or higher should work. For Solaris binaries, for example:
      $ /usr/local/gnu/bin/tar -zxvf mysql-3.23.37-sun-solaris2.7-sparc.tar.gz
      $ cd mysql-3.23.37-sun-solaris2.7-sparc
      $ scripts/mysql_install_db
      $ ./bin/safe_mysqld  &
    

    See the installation instructions of mysql in case of problem.

  2. Be sure to set the appropriate permissions so that the user in the SQL URL can access the tables. For example:
      # start mysql client to connect to database "mysql" on localhost
      # as user root. You may need password if configured.
      $ mysql -hlocalhost -uroot mysql
    
      # grant permissions for user root on localhost for all database.
      mysql> GRANT ALL PRIVILEGES ON *.* TO root@localhost WITH GRANT OPTION;
    
      # update the privileges.
      mysql> FLUSH PRIVILEGES;
    

    The above example does not use any password. The SQL URL would be sql://root:NULL@localhost/sip. If you intend to use a password, then the permissions are granted by the following line and the SQL URL becomes sql://root@mypassword@localhost/sip.

      mysql> GRANT ALL PRIVILEGES ON *.* TO root@localhost \
             IDENTIFIED BY 'mypassword' WITH GRANT OPTION;
    

    When mysql is installed, it has all privileges for user root without any password on localhost. Users are strongly encouraged to change the privileges for specific hosts and a specific user and password.

  3. Check whether Tcl (version 8.3 or higher) is installed locally and reachable by the web server.
  4. The system assumes that the file index.cgi is invoked when you use just the directory name; if your local configuration does not support this, you may need to invoke the cgi file explicitly, as in
      http://www.example.com/cgi-bin/cinema/index.cgi
    

    To configure the Apache web server to accept index.cgi as a directory index, include the following lines

      Options ExecCGI
      AddHandler cgi-script .cgi
      DirectoryIndex index.shtml .index.html index.html index.cgi
    
    in your httpd.conf file. The remaining steps can also be automated with a script.
  5. Create the CINEMA-related database tables using the createsip.sql script in the scripts directory of the distribution.

      # set the PATH environment variable to include your mysql/bin directory
      # For example on with sh or bash shell you can do:
      $ export PATH=/mysql-install-dir/bin:$PATH
    
      # Go to CINEMA installation directory.
      $ cd /cinema-install-dir
    
      # Create the SIP database
      $ mysql -u root < scripts/createsip.sql
    
    If you have already installed the database for the previous release then you should use altersip.sql script instead.
      # Upgrade the SIP database from previous release
      $ mysql -u root < scripts/altersip.sql
    
  6. You must add the first administrator user with the addsipuser script present in the tools directory. For example, the following command adds the first user with userid david@example.com, with password as italy and realm as example.com. The user is a administrative user (-a option). The SQL database for sip is accessed on localhost with userid as root and no password. The default user record is automatically added with the -f option.
      $ ./addsipuser -d sql://root:NULL@localhost/sip \
         -u david@example.com -p italy -r example.com -a -f
    
    Users are strongly encouraged to change the privileges in their SQL database to disallow eavesdropping.
  7. Copy the cgi files in cinema/web to a directory where your web server expects cgi-bin files. Depending on the local web server configuration, this can either be a special directory, typically called cgi-bin, or any directory below the document root. The GIF files are in the same directory. If you are using Apache web server, you may prefer to have a handler for cgi files in your httpd.conf file.
      AddHandler cgi-script .cgi
    
    Our system assumes a .cgi extension for cgi-scripts.

    The directory containing the cgi scripts must have appropriate permissions to execute the scripts as well as display the images. For example, in one configuration where the cinema/web directory is copied to apache/htdocs/cinemaweb directory the following line provides access to cgi scripts and images.

    <Directory "/apache-install-dir/apache/htdocs">
      Options Indexes FollowSymLinks ExecCGI MultiViews Includes
      AllowOverride None
      Order allow,deny
      Allow from all
    </Directory>
    
    You will need to make appropriate modification in the configuration file if you wish to put the cinema/web directory under your cgi-bin directory of the Apache server.
  8. Copy the programs md5string and random32, and the shared library libfbsql.so, from their locations underneath the cinema tools directory into the web installation directory.
  9. All our CGI scripts assume the default path for tclsh as /usr/local/bin/tclsh. If the path is different in your installation, you need to modify the scripts to update this. For example if the tclsh is present at /tcl-install-dir/bin/tclsh you can use the following Unix command.
      $ cd /cinema-web-install-dir
      $ for x in *.cgi *.tcl
      > do
      > sed 's/\/usr\/local\/bin\/tclsh/\/tcl-install-dir\/bin\/tclsh/g' < $x > tmpfile
      > mv -f tmpfile $x
      > done
    
  10. Change the permissions of all the files in the web installation directory so that they can be accessed from the web server.
      $ cd /cinema-web-install-dir
      $ chmod -R 755 .
    
  11. rtspd specific: Edit the rtspd/rtspd.conf file. See rtspd/docs/rtspd.html for details.
  12. sipum specific: Edit the sipum/script/config file. See sipum/docs/sipum.html. Copy the directory sipum/audio to the directory where per-user voice messages are supposed to reside. Alter the default values for the MySQL tables for sip_groups, busy, noresponse and um_timeout.
     mysql>ALTER TABLE put ALTER COLUMN sip_groups 
                  SET DEFAULT 'cgi voicemail';
     mysql>UPDATE put SET sip_groups='cgi voicemail' 
                  where user='default@yourdomain';
     mysql>UPDATE put SET sip_groups='cgi admin voicemail' 
                  where user='youruserid@yourdomain';
     mysql>UPDATE put 
             SET busy='rtsp://SERVER/audio/welcome.au',
                 noresponse='rtsp://SERVER/audio/welcome.au',
                 um_timeout='15';
    
  13. Edit the cinema.conf file in the web directory to point to your MySQL server. You may edit other values at this time as well, or you may subsequently use the ConfigureMenu.cgi script for a web interface to the configuration.
  14. Use the ConfigureMenu.cgi script to set up sipd.conf. In particular the sipd configuration options you MUST update are (1) the regular expression defining the domains that the server accepts registrations from, (2) userid as which the server will answer requests, (3) DNS name for which this server will accept registration, and (4) the SQL 'URL' for the user database, e.g., sql://root:NULL@localhost/sip if there is no password and user root is allowed to access from localhost. You must give the host name of the host running the sipd server and SQL server are running on different machines.
  15. Start sipd using the start-sipd script. See the sipd manual for details. It is recommended to use the -v (verbose) and -X (non-daemon mode) options for the initial tests.

     $ cd /cinema-install-dir
     $ sipd/start-sipd -v -X -s .
    

Installation script for binary installation on Unix

You can use the Tcl installation script install.tcl available with the distribution to install the system. It asks you few questions and performs steps (5) through (12) of the binary installation described above. You must perform steps (1) through (4) before running the install.tcl script. The last step is to check whether sipd executes correctly or not.

Note that the installation script will automatically try to install all the available modules (e.g., sipd, rtspd, sipum). If you are not using the installation script, please be careful on what module to install and configure.

Installation using Binaries on Windows

Not all applications can be compiled on Windows. Please see the appropriate application specific documentation (e.g., sipd.html, sipum.html) for details on what platforms are supported.

The Windows installation is similar to the manual Unix installation. The binary distribution also contains the required DLLs and EXEs for various tools. Both debug and release versions of the EXEs are provided. Alternatively you can run the install.tcl script after you perform steps (1) through (4):

  $ cd \cinema-install-dir
  $ \tcl-install-dir\bin\tclsh84.exe ./install.tcl

You will need to perform all the steps, with the following exceptions:

  • In step (8) copy the md5string.exe, random32.exe and fbsql.dll to the web directory.
  • Step (9) does not work on Windows. You can change the paths manually, or use the script tclpath.tcl in the scripts directory. You must edit the first three lines manually to give the locations of your sipd installation directory, your web directory, and your Tcl executable.
  • Step (10) can be done using Windows Explorer. This step may not be needed for most installations.

    Do the following steps even if you are using the install.tcl script:

  • Before step (12), you must edit the file web\where.tcl to change
    load ./libfbsql.so
    to
    load fbsql.dll
  • Also before step (12), copy the file sipd.conf_win32 to sipd.conf.
  • Copy the file NT\resparse-1.3\resolv.conf to sipd's server root, and edit it to point to your local DNS servers.
  • The last step is not needed (and will not work) for Windows. Use sipd instead of start-sipd.
      $ cd \cinema-install-dir
      $ Release\sipd.exe -v -X -s .
    

Future versions will use a self extracting installation program and will be simpler.


Last updated by Henning Schulzrinne