Already registered? Login
Home > TechZone > Documentation > Linux install > Linux Installation > Installation guide 
Installing Metadot Portal Server

This page provides the basic information for installing Metadot Portal Server. You may want to print this page to have these instructions on hand during the installation.

The lastest version of this document is available at www.metadot.com.

Please go to the Metadot forum to get install advise from the community (again at www.metadot.com).
Additional help for Windows users can be found here.

This section includes the following topics:

New installation

  1. Minimum requirements
  2. Installing Perl
  3. Installing Apache or IIS
  4. Setting up the database
  5. Installing Perl modules
  6. Creating a Metadot user
  7. Extracting Metadot files
  8. Configuring the database and database user
  9. Setting up Metadot configuration file
  10. Configuring the web server
  11. Setting up the Metadot background tasks
  12. Testing the installation
  13. Configuring Metadot Portal Server
  14. Configuring Single-Signon (SSO) authentication
  15. Metadot documentation

This page describes the steps necessary to install Metadot. If you are starting from an existing Metadot installation, then see the upgrade instructions located somewhere else!

 

New installation

Minimum requirements

  Linux     (check README for tested distributions)
Apache 1.3.6
Perl 5.005_03
mod_perl 1.21
MySQL 3.23.xx (older versions will be incompatible with the table definitions used).
- OR -
Oracle 8.1.17 or higher

Note: The Metadot software runs on Solaris as well, although the mod_perl installation process will be different than that described for Linux below; and LDAP connectivity has not been tested with Solaris.

Note: The lastest open-source version of the Portal Server does support Oracle.

This version of the Metadot Portal server is not officially supported on Windows; however, if you prefer to run it on Windows, you will likely be successful. Instructions for Windows installation are included in this document.

For Windows, you will need:

  Windows NT/Windows 2000 Service Pack 2
IE 5.5 Service Pack 1
IIS
Active Perl 5.6 build 633
Perl-EX v. 2.2
MySQL
- OR -
Oracle 8.1.17 or higher

Installing Perl

Linux:

Just about all distributions automatically install Perl for you upon installation of the system. Check to make sure you are using a new enough version using the following command :
        perl -v

If you need to upgrade your perl installation, you can find it at http://www.perl.com/CPAN/

WARNING: There have been some reports of problems between Perl 5.6.0 and mod_perl 1.24 on Red Hat 7.0 systems. If you experience problems, download the latest relevant patches from Red Hat.

Windows:

Install ActivePerl 5.6 build 633
(http://aspn.activestate.com)

(As of this writing, the current version of ActivePerl is incompatible with the Metadot product, because it does not yet support the modules needed for Metadot to run).

Installing Apache with mod_perl (Linux), or IIS (Windows)

Linux:

Apache can be downloaded from http://httpd.apache.org/.
mod_perl can be downloaded from http://perl.apache.org/

The versions of Apache and mod_perl that ship with Red Hat 6.2 and 7.1 have been extensively tested with the Metadot product and work fine. If you are working on a Red Hat (or Red Hat-derived) Linux distribution, the RPM versions of these applications can be used without having to compile and install them by hand.

We recommend installing Apache with mod_perl as a DSO. To do this, extract Apache and mod_perl. change to the extracted mod_perl directory and do the following commands :

        $bash mod_perl-x.xx > perl Makefile.PL APACHE_SRC=../apache_x.x.x/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 USE_DSO=1
$bash mod_perl-x.xx > make
$bash mod_perl-x.xx > make test
$bash mod_perl-x.xx > make install
$bash mod_perl-x.xx > cd ../apache_x.x.x
$bash mod_perl-x.xx > make install

apache_x.x.x is the extracted apache directory.
"$bash mod_perl-x.xx>" is a representation of the prompt and is not part of the command.

For more information on building mod_perl try : http://perl.apache.org/guide/install.html

Windows:

Configure IIS according to the section "How do I configure Microsoft IIS 4.0/IIS 5.0 to support ActivePerl?" which is contained under the "Web Server Config" item of the ActivePerl documentation. Make sure you add a global application mapping for .pl files that points to perl.exe.

Setting up the database

MySQL

MySQL can be found at

  http://www.mysql.com/
http://www.mysql.com/downloads/index.html
will provide the most recent stable version. Version 3.23 or above is required.

If installing MySQL from RPM, you will need to install the MySQL client RPM and the MySQL devel RPM. If you do not have these installed, you will likely run into serious problems when trying to build the Perl Modules in step 4.

The MySQL 3.23 RPMS that ship with Red Hat 7.1 and higher have been extensively tested with the Metadot product and are known to work well.

Once the MySQL server is installed, you will need to make sure it's running. You can do this by simply trying to connect to it. If it is not running, you can start it manually with the following command (linux):

   $bash > /usr/bin/safe_mysqld & 

(your safe_mysqld may be in a different location)

For Windows:

Add the mysql directory to the windows search path, so MySql commands are available to the metadot daemon. Here's how to do this:

  Right-click on "My Computer" icon.
Select "Properties".
Select the "Advanced" tab.
Select "Environment Variables".
Edit the "Path" variable in "System Variables".
If you don't see an entry for mysql, append the mysql bin directory (i.e. ";c:\mysql\bin).

Oracle Users

Install Oracle client for your operating system

Create a user and schema for the Metadot database. If desired, create a tablespace as well. This user must be able to CREATE TABLE.

Set up the Metadot schema using the command:

   
sqlplus / < /oracle_setup/oracle_schema.sql

Import the data contained /oracle_setup/expdat.dmp, using the command:

   imp / file=/oracle_setup/expdat.dmp ignore=y full=y

Installing Perl modules

Linux:

Perl Modules can be downloaded from http://www.perl.com/CPAN/. There are two ways to install the perl modules. You can download the tarballs for them and build them yourself, or you can let perl do all the work for you. We recommend letting perl do all the work for you. This is how :
     $bash > perl -MCPAN -e shell
cpan> install  

This system will check dependencies and install them as well.

SPECIAL NOTE ON CPAN
------------------------------
There is a problem with recent versions of CPAN that can lead to many problems during a Metadot installation. A specific module, when being installed by CPAN, will try to upgrade your system to Perl 5.6.1. While there is nothing wrong with this version of Perl, it can cause serious issues if it takes place at the wrong part of this installation process.
Metadot highly recommends that you issue the following command in the CPAN shell before installing any modules:

o conf prerequisites_policy ask

This will force CPAN to ask you if you wish to install dependent modules that are not already on your system. Dependent modules normally need to be approved for all of the Perl modules to work properly. The one current exception is during the installation of Msql-Mysql-modules. It will prompt for the installation of Data::Dumper. DO NOT APPROVE
THIS INSTALLATION. Msql-Mysql-modules will work fine with the version that is on a Perl 5.004 or 5.6.0 system.

The one exception to this is the expat library. It is needed for the XML::RSS module to install. For every platform but FreeBSD, the expat library can be downloaded from its homepage at http://expat.sourceforge.net/ It may be installed with the following procedure. Incidentally, this is also the procedure you would follow if you wanted to build the perl modules yourself :

        $bash expat_x.x > ./configure
$bash expat_x.x > make
$bash expat_x.x > make install

For a FreeBSD installation:

Do not install expat from source or ports, and do not install the perl module XML::Parser from source or cpan. Instead, install the perl module XML::Parser from ports. Doing so will fetch and compile expat, and then tie expat properly to the perl module XML::Parser.

To install the XML::Parser module from ports, change to
/usr/ports/textproc/XML-Parser

Once in that directory, type
make && make install

If you have chosen not to install the ports system with your FreeBSD installation, XML::Parser can also be installed from the FreeBSD packages collection. Installing via packages will also correctly fetch expat and tie expat to the XML::Parser module.

To install XML::Parser via packages, type
/stand/sysinstall.
Then, choose Configure, Packages, textproc, and then the XML::Parser package.

Once expat is installed, you should be able to install the rest of the modules with no problems using the following commands (Many of the required modules are installed automatically as dependencies when these commands are run) :

   
$bash > perl -MCPAN -e shell
cpan> install LWP
cpan> install DBI
cpan> install Bundle::Mysql
cpan> install Apache::DBI
cpan> install XML::RSS
cpan> install Storable (Only needed for Metadot version 6.3.x and below. No longer needed on >= 6.4.x)
cpan> install Net::LDAP
cpan> install Log::Agent
cpan> install Mail::POP3Client
cpan> install IO::Stringy
cpan> install Mail::Internet
cpan> install MIME::Tools
cpan> install Unicode::String
cpan> install Spreadsheet::WriteExcel
cpan> install Date::Calc
cpan> install AppConfig
cpan> install Image::Size
cpan> install Template
cpan> install Time::HiRes
cpan> install Lingua::EN::NameParse
cpan> install Number::Format
cpan> install XML::Simple
cpan> install Text::CSV_XS
cpan> install Archive::Zip
cpan> install Date::Manip
cpan> install XML::Dumper
cpan> install HTML::TreeBuilder
cpan> install HTML::FormatText

Notes:
Lingua::EN::NameParse is needed only for the upgrade script.
It appears that under some circumstances, using the CPAN module to install XML::Simple will also cause the installer to attempt to install a version of XML::Parser incompatible with mod_perl. See this page and the links it provides for more info. To control the install, you may want to install XML::Simple using the tar file obtained directly from the cpan.org site, rather than utilizing the CPAN module.

Windows:

Install the following Perl modules using the command line PPM (PPM was installed as part of Active State Perl).

As of this writing, it is suggested that modules should be installed from the old ppm repository at ActiveState because the newer one apparently no longer contains several of the required modules.

To use the old repository, run the following set command:

PPM> set repository old_as http://www.activestate.com/PPMPackages/5.6

Having done this, you should be able to install the following modules:

        ppm        
ppm> install DBI
ppm> install DBD-Mysql
ppm> install Storable
ppm> install Date-Calc
ppm> install Perl-LDAP
ppm> install XML-RSS
ppm> install Mail-POP3Client
ppm> install IO-stringy
ppm> install MIME-Tools
ppm> install Unicode-String
ppm> install Spreadsheet-WriteExcel
ppm> install Time-HiRes
ppm> install Image-Size
ppm> install XML-Simple
ppm> install Number-Format
ppm> install Text-CSV_XS
ppm> install Archive::Zip

ppm> set repository oi http://openinteract.sourceforge.net/ppmpackages
ppm> install AppConfig
ppm> set repository oi http://openinteract.sourceforge.net/ppmpackages
ppm> install Template-Toolkit

(The latter group of commands grab two ppm packages from a different site. They may also be obtained from soulcage.net via:
PPM> set repository soulcage http://www.soulcage.net/ppds/
).

To run the upgrade script, you will need to install the Lingua-EN-NameParse module, which can be found here:
http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/

When the perl modules listed have all been installed, you can do a quick check using the PPM query command to verify that all the required modules are installed (several modules have dependencies which cause other modules to be installed).

Creating a 'metadot' user

Linux:

We recommend that you create a user to own the metadot files. Many distributions have their own way to add a user to the system. Refer to your distribution's documentation for how to do this. Alternately, on most systems, you can add a user with the following command:

        $bash > useradd -m metadot
$bash > passwd metadot

This document assumes you have created a user and that user will be referred to as "metadot" for the rest of the instructions. You may name this user anything you wish.

WARNING : Only do this next piece if you are sure of what you are doing. Making a mistake in the /etc/passwd file can have serious negative consequences.

For extra security, you may wish to disable the ability to log in as the metadot user. To do this, edit the /etc/passwd file. Look for the line for the metadot user and change its default shell to /bin/false.

Windows

Create a 'metadot' user by selecting (from the windows desktop):

    Start -> Settings -> Control Panel -> Users and Passwords.

Select "Add..." and the Add New User wizard will start. Fill in "metadot"
for the user name and press the "Next" button.
Accept the default "Standard user" for the level of access, then
select "Finish".

Extracting Metadot files

The Metadot tarball can be found at http://www.metadot.com

In the remainder of this document, "" will be used to indicate your top-level metadot directory, for both the Linux and Windows installations.

For example, if on linux your top-level metadot directory is:
/home/metadot/metadot

then in the rest of the instructions,
replace "" with
"/home/metadot/metadot".

If on Windows, your top-level metadot directory is:
C:\metadot

then in the rest of the instructions, replace "" with
"C:\metadot".

Linux:

Extract the Metadot files into your metadot user directory. Change to the metadot user directory and extract the tarball from there.

The tarball can be extracted with the following command :

        $bash > tar -zxvf metadotvx.x.tar.gz
(Some variants of Unix do not support the -z arg and may require you to gunzip the tar file first).

You will want to make sure that the metadot user directory has its permissions set to allow read and execute by group and other. You can do this with the following command. For example, if your user is named "metadot":

    $bash > chmod ugo+rx /home/metadot

WARNING : If your system has local users, you will need to change the permissions to be secured from the local users. Use the following commands :

    $bash > cd /etc
(where, as indicated above, is the top-level directory
of your Metadot installation).

$bash > chown root.nobody metadot.conf
$bash > chmod 640 metadot.conf
$bash > chown root.nobody /home/metadot
$bash > chmod 750 /home/metadot

This assumes that the web server is part of a group called "nobody". You can find out what group your web server is in by looking in its httpd.conf file. We will be editing that file in a later step.

Windows:

Unpack the tarball into an appropriate directory.

Make sure that directory \metadot (where the script metadotd.pl resides) grants write and show permissions to both 'Administrator' and 'metadot'.

Make sure the 'channels' directory (under \metadot) grants write permission to both 'Administrator' and 'metadot', and that all the files within it do as well.

Make sure that the 'html' directories and files under them grant read, write and show permissions to the 'metadot' user.

Configuring the database

Linux:

First we need to create the database for the Metadot installation to use. Change to the default_data subdirectory using the following command (where you replace with the location of your installation:

        $bash > cd /default_data

Then create the database using the following command :

        $bash > mysql -uroot mysql < createdbanduser.sql

Create the database using the following command if using MySQL 4.x:

        $bash > mysql -uroot mysql < createdbanduser4x.sql

If you have specified a password for the mysql server root user, add "-p" before the second "mysql" and you will be prompted for the password.

You should immediately change the default password for the new database user. Do this with the following commands :

     $bash > mysql -uroot mysql
mysql > update user set password = password('<newpassword>') where user = 'metadot';
mysql > flush privileges;
mysql >quit

<newpassword> should be replaced by what you want the password to be. "mysql >" is a representation of the mysql command prompt and is not part of the command.

Note: it is required to define some password for the metadot user; the system will not work without a password defined.

Next, load the default data into the database.

     $bash > mysql -umetadot -p metadotdb < sampledata.sql

Windows:

     a) From the Start->run menu run the cmd command.

b) Change directory to <metadot>\metadot.

c) Run the command:

mysql -uroot mysql < createdbanduser.sql

d) You should immediately change the default password for the
new database user. Do this with the following commands :

mysql -uroot -p<root_password> mysql

mysql > update user set Password = password('<newpassword>') where User = 'metadot';
mysql > flush privileges;
mysql > quit

<newpassword> should be replaced by what you want the password to be.
"mysql >" is a representation of the mysql command prompt and is not part of
the command.

e) Load the metadot database:

mysql -umetadot -pnewpassword metadotdb < sampledata.sql

Setting up Metadot configuration file

Metadot uses a configuration file that associates database information with the web server that you are running. It is called:
/etc/metadot.conf

This file can contain one or more "configuration blocks", each of which have the following syntax:

  [<blockname>]
name = dbi:mysql:
user = <dbuser>
pass = <dbpassword>
dbtype = MySQL
# use the following to enable Default authentication
registration_type = Default
authenticator_type = UserPassAuthenticator
# use the following to enable LDAP authentication
#registration_type = LDAP
#authenticator_type = LDAPAuthenticator

(etc. for additional attribute-value pairs)

servers = <
localhost
[address2]
...
[addressN]
SERVERS

 

Typically a system will be configured to use just one server block. Multiple configuration blocks can be used to enable the use of virtual servers, and to allow one web server to run off the same perl code base. We suggest that you do not experiment with using virtual servers until the system is running to your satisfaction in single-server mode. More information about the 'virtual server' feature is below.
 

Configure Metadot to connect to a remote database

 In some of the first few lines of the configuration file, all the database connection information is configured. By default this configuration assumes that the database is located on a local machine.

Metadot is capable of connecting to a database located on a server completely independent from the webserver.

 The key is in this line:

# Name of database to be used

name = dbi:mysql:metadotdb

 This basically tells metadot to connect to a MySQL database called metadotdb, since no connection information is supplied it assumes that database is located on the local host.

 If that line becomes this:

# Name of database to be used

name = dbi:mysql:metadotdb:192.168.1.1

 
Then Metadot will attempt to connect to a MySQL database called metadotdb located on 192.168.1.1

Single-server configuration

Get your server running first in single-server mode. You only need one configuration block. Follow the example in metadot.conf. The SERVERS list must include "localhost" as in the metadot.conf file, and should not include any other address. [On linux, the SERVERS list may include other addresses to no detrimental effect, but on Windows it may not].

Next, edit the database information in metadot.conf so that it is correct for your environment. If you followed the instructions above, you should not need to change the database name from "metadotdb", and the user should be "metadot". Follow the example comments in the file to change the database type to Oracle.

The registration, user type, and authentication method are by default set to the following values:

registration_type = FlexRegister
user_type = FlexUser
authenticator_type = UserPassAuthenticator
which you will not need to edit unless you are changing them. (You do not need to uncomment these values in the metadot.conf file).

The metadot.conf file now controls whether or not the site uses LDAP authentication and registration. This is new in version 4.5. As indicated in the example above, comment out the 'Default' lines and uncomment the 'LDAP' lines in the .conf file to use LDAP for your site.

With Version 4.6.1 and higher, the metadot.conf file specifies both the absolute path and the web server path for a 'public' uploads directory. In the metadot.conf file, you will see lines like this:

# the following must be uncommented and set to the appropriate values
# to support uploads to a publicly accesible directory
public_uploads_dir = /home/metadot/metadot/sitedata/public
public_uploads_location = /public

Your web server must then be configured consistently with the information in the metadot.conf file, as discussed in the section Configure the Web Server. E.g., in the example above, the web server must configured such that /public is aliased to the given directory path on the server.

Remember the location of the public directory that you create. In the section Configuring Metadot, you will need to copy some sample data files to this directory.

Similarly, with Version 6.0 and higher, the metadot.conf file specifies the absolute path for a 'skins' uploads directory. In the metadot.conf file, you will see lines like this:

# Skins directory: specify the directory where template files for skins are located.
# This directory must be readable by the process running Metadot Portal Server.
skin_template_dir = /home/metadot/metadot/sitedata/skins

Change the lines to the absolute path pointing to the directory you want to use for skins. The relative URL for this path must be '/skins', in order for the default templates to properly load their CSS and image files.

Virtual server configuration

[Get your system running in single-server mode first, before configuring it to use virtual servers. ].

The /etc directory contains two example configuration files, one for Linux and one for Windows. If you use one of those example files as a starting point, remember to rename it to metadot.conf. You might want to back up the original version of metadot.conf first.

The use of multiple virtual servers, all accessing different databases but the same code base, can be enabled by using multiple configuration blocks. Each configuration block contains its own database configuration, and a list of server addresses to be associated with that database configuration information. The database information must be different across multiple servers-- if you are going to run multiple servers, they should not access the same database.

Linux

An example file is listed below with multiple configuration blocks. Note that each block has a different database configuration. Each configuration block contains a list of SERVERS. One of the configuration blocks must include 'localhost' in the list of servers. When a user accesses metadot via a web browser, the system determines what configuration block to use based on the name of the (virtual) server accessed by the user request. If a user accesses the metadot portal via a server address not listed in the config file, the request will default to the configuration block whose server list contains 'localhost'.

 


  [metadot1]
  name = dbi:mysql:metadotdb
  user = metadot
  pass = xxx
  dbtype = MySQL
  (etc..)
  servers = <

Windows

An example file is listed below with multiple configuration blocks. Note that the 'localhost' block defines the same database configuration information as the second block, and the third configuration block defines a different database. Each configuration block contains one SERVER address. One of the configuration blocks must use 'localhost' as its server address.

When a user accesses Metadot via a web browser, the system determines what configuration block to use based on the name of the (virtual) server accessed by the user request. If a user accesses the metadot portal via a server address not listed in the config file, the request will default to the configuration block whose SERVER address is 'localhost'.

Unlike Linux, on Windows the configuration blocks can contain only one address per block. So, the block that contains 'localhost', and is the "default" block, should contain the same database configuration information as one of the other blocks-- and that database will then be accessed as the default.


  [metadot1]
  name = dbi:mysql:metadotdb
  user = metadot
  pass = xxx
  dbtype = MySQL
  (etc..)
  servers = <

Set up 'html', 'private', 'public', and 'skins' directories for each server

If you are running multiple servers, each with their own database, then you will need to create different 'images', 'private', 'public', and 'skins' directories for them. This is described in the Configuring Metadot section below. When you get to that section, you will need to configure this information separately for each server.

Configure the web server

Linux: Configure httpd.conf

The httpd.conf file is usually in /etc/httpd/conf/httpd.conf or /usr/local/apache/conf/httpd.conf. Edit this file with your favorite editor.

Check to make sure the following lines are in the file:

  • LoadModule perl_module
  • modules/libperl.so
  • AddModule mod_perl.c

(Note that you won't need these lines if your Apache server was compiled with a statically linked mod_perl module, which will not be the case if you follow the above instructions on building Apache).

Sometimes modules/libperl.so won't be there, but libexec/libperl.so will be there. This is acceptable.

Add the following lines to your httpd.conf :

        Alias /images/  <metadot>/html/images/
Alias /js/ <metadot>/html/js/
Alias /metadot/ <metadot>/metadot/
Alias /public/ <metadot>/sitedata/public/
Alias /skins/ <metadot>/sitedata/skins/

<Location "/metadot">
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
</Location>
Note: Replace <metadot> with the correct path in your system. For example, if you are installing Metadot under /home/metadot, then the correct path will be /home/metadot/metadot

Make sure that this directory is writable by the apache process owner, which is typically either "nobody" or "apache".

 

Make sure PerlSendHeader is not set to On in the httpd.conf script.

Locate the section in the file that deals with DocumentRoot. Replace the existing entry for the /apache/htdocs with one for the metadot location:
/html

Locate the section in the file that deals with DirectoryIndex. Certain browsers have an issue with the way that redirects are issued within the Metadot system. As such, a redirection to /metadot/ will fail because indexing is not allowed within the Metadot . Add 'index.pl' to the list following DirectoryIndex and this will no longer be a problem.

Then, you will need to configure your metadot.conf file to properly specify the 'public' and 'skins' directory information for the Metadot software.

Metadot Virtual Servers

If you have set up your metadot.conf file to use multiple server blocks (virtual servers), then you will need to configure your apache httpd.conf file to define the /public, /skins and /images aliases above for each metadot virtual server. You can do this by using the VirtualHost construct, or alternatively you can use mod_rewrite and rewrite rules to support accessing distinct directories for each virtual server.

(The /images directory may potentially be shared if you like; however, the /public directories may not, since the users of each virtual server can show the /public directory contents for their server). The /skins directory can optionally be shared, which will cause any uploaded skins to become available across all virtual servers, and any changes to the skins will affect all virtual servers.

Restart Apache

Each time that you edit the httpd.conf file or any of the files in the metadot directory, you will need to restart your web server. Do this with the following command (replacing the path below as appropriate):

  $bash > /usr/local/apache/bin/apachectl restart

Windows:

Go to the IIS Manager console and create the following virtual directories under the default website. To achieve this you have to left-click on the default website icon and run the New->Virtual Directory wizard.

     a) "metadot" alias:  make it point to \metadot, and make sure 
you add 'execute' permission to it in the Access Permissions page in
the wizard.

b) "images" alias: make it point to \html\images".
c) "js" alias: make it point to \html\js".
d) "htmlarea3" alias: make it point to \html\htmlarea3".

Create a "public" graphics directory

Metadot version 4.6.1 and higher has a new feature which allows users to upload files to a public, web-accessible, directory as an alternative to the access-controlled uploads directory described below. Once you create this directory, you will need to tell the IIS web server where it is, similarly to the line above in which the /images/ directory is configured. For example, if you want the public directory to be reached from the web server via /public, and the actual path of the directory is /sitedata/public, then you would add an alias like this:

      d)  "public" alias: make it point to  \sitedata\public

Then, you will need to configure your metadot.conf file to properly specify the 'public' directory information.

 

Create a "skins" directory

Metadot version 6.0 and higher has a new feature which allows administrative users to manage and upload skins. Each skin will contain files that must be publicly accessible on the web server. Once you create this directory, you will need to tell the IIS web server where it is, similarly to the line above in which the /public/ directory is configured.

Then, you will need to configure your metadot.conf file to properly specify the 'skins' directory information.

Open the IIS control panel:
Start -> Settings -> Control Panel -> Administrative Tools -> Internet Services Manager

Expand the node for the host to see the Default Web Site. Right-click and select Properties. Select Home Directory tab. Use the Browse button to select the directory /metadot (where the file index.pl resides).

Select Documents tab, select Add... and create an entry for index.pl; move it to the top of the list if there are other entries.

Change the user under which IIS runs Metadot.

  • Go to the IIS virtual directory properties.
  • Select the "Directory Security" tab.
  • Click on the Edit button for "Anonymous Access and Authentication control".
  • Make sure the "Anonymous Access" checkbox is selected and click the Edit button for "Account used for anonymous access".
  • Click on "Browse" and select the "metadot" user.
  • Enter the password from 7. Make sure the "allow IIS to control password" checkbox is not selected.
  • Click OK on all open dialog boxes. Go back to the control panel, select Services, right-click on World Wide Web Publishing Services, and select Restart (select Start if the service is not running)

Configure mime.types

Add the following mime types to the mime.types file (if they do not already exist). The mime.types file is usually in /etc/mime.types.

        application/vnd.ms-word doc       
application/vnd.ms-excel xls xlt
application/vnd.ms-powerpoint ppt
application/vnd.ms-project mpp
(If you don't have a mime.types file, you can add appropriate AddType lines to your httpd.conf file).

Set up the Metadot background tasks

Two background tasks must be enabled for the Metadot portal to run properly. One handles cleaning tasks and the other handles channel management.

Linux: Add cron entries for Metadot

We will need to add several lines to the cron table next. The crontab will be used to run the metadot daemons, which automate cleaning tasks, updating channels and sending notifications. The following will tell the crontab to run the channel update every 20 minutes, and to perform cleaning once a day. To do this, we will use the following command to edit the cron table:

     $bash > crontab -e

Add to the cron table the following lines :

*/20 * * * * cd /home/metadot/metadot/metadot; nice -19 perl metadotd.pl -m -s >/dev/null 2>/dev/null
Metadot's background script has the ability to support an "email-to-discussion" functionality, where users subscribed via email in "ASAP" mode to discussion groups can reply to the discussion message emails and have them incorporated into the website discussion thread. If you would like to enable this capability, show the line above to be instead:
*/20 * * * * cd /home/metadot/metadot/metadot; nice -19 perl metadotd.pl -m -s -fetch >/dev/null 2>/dev/null
Then, you will also need to create an email account that can be used to hold discussion message replies, and configure Metadot to use this account. Read the subsection below that describes this feature in more detail, then see the section on Configuring Metadot.

Then, add the line below to the cron table as well:

18 1 * * * cd /home/metadot/metadot/metadot; perl metadotd.pl -o >/dev/null 2>/dev/null
This last line checks once a day for any wedged metadotd invocations.

Then, add an entry to the cron table to do cleanup:

38 1 * * * cd /home/metadot/metadot/metadot; perl md_clean.pl -c -o>/dev/null 2>/dev/null
or
38 1 * * * cd /home/metadot/metadot/metadot; perl md_clean.pl -c -e 10 -o>/dev/null 2>/dev/null
The cleanup activities include removing old data from the event_log database table. If you have event logging enabled, it is very important to run this script, so that the event_log database table does not get too big. The optional "-e" argument specifies to the script to remove data over N days old from the event_log table. For example, the line above tells the script to remove data over 10 days old. This is only an example; adjust this number to suit the needs of your site. The event log cleanup interval may also be specified in the admin's system configuration interface, under the "Manage" --> "Config" pulldown menu. The command-line argument above will override the value set in the configuration interface. So, if you wish to control this interval from the web interface, do not include the "-e" argument in the cron command above.

When you are done editing the cron table, you may review the table with the following command :
$bash > crontab -l

Windows:

Add a scheduler entry for the metadotd background job:
  • Make sure you are logged in as Administrator, and from the windows desktop
    go to:
    Start -> Settings -> Control Panel -> Scheduled Tasks
  • On the Scheduled Tasks window do a left-click and select New->Scheduled Task.
    Give the new task the name "metadotd".
  • Open the new task properties by left clicking on it.
  • In the 'Run:' textfield of the 'Task' tab enter:
    C:\perl\bin\Perl.exe \metadot\metadotd.pl -m -s
    (show the line above if you installed perl into a different location).
    Note: It is important to include both the full path to the Perl executable, and to the perl script, in the above.
  • In the 'Start in:' textfield of the 'Task' tab enter:
    \metadot
  • Go to the 'Schedule' tab and make sure the 'Schedule Task' box is set to 'Daily'.
  • Click on the 'Advanced' button and check the 'Repeat Task' box and configure it to 20 minutes with a duration of 24 hours.
  • Click OK on all open dialog boxes and enter the Administrator password when
    prompted for it.

The metadotd job will run every 20 minutes and a cmd window will appear on the desktop when that happens. It should take from a few seconds to a few minutes for it to run, depending on how fast your internet connection is.

Metadot's background script has the ability to support an "email-to-discussion" functionality, where users subscribed via email in "ASAP" mode to discussion groups can reply to the discussion message emails and have them incorporated into the website discussion thread. If you would like to enable this capability, show the line above to be instead:

C:\perl\bin\Perl.exe \metadot\metadotd.pl -m -s -fetch

Then, you will also need to create an email account that can be used to hold discussion message replies, and configure Metadot to use this account. Read the subsection below that describes this feature in more detail, then see the section on Configuring Metadot.

Next, repeat the process above, but with a Run line of:

C:\perl\bin\Perl.exe md_clean.pl -c -e 10 -o

and set this invocation of the script to run once a day. This will clean old session and event log information. If you have event logging enabled, it is very important to run this script, so that the event_log database table does not get too big. The -e argument in the example above cleans the event log table of all events older than 10 days. Change this number to suit the needs of your site. The event log cleanup interval may also be specified in the admin's system configuration interface, under the "Manage" --> "Config" pulldown menu. The command-line argument above will override the value set in the configuration interface. So, if you wish to control this interval from the web interface, do not include the "-e" argument in the scheduler command above.

 

Next, again repeat the process above, but with a Run line of:

C:\perl\bin\Perl.exe \metadot\metadotd.pl -o

and set this invocation of the script to run once a day. This will clear any old lock files that may have been generated.

You can check the scheduled tasks by selecting (from the Windows desktop):

   Start -> Settings -> Control Panel -> Scheduled tasks

(you have to double-click the Scheduled Tasks item to show all tasks).

The "email-to-discussion" feature of the metadotd.pl script

The "email-to-discussion" feature is new to Version 4.0.

If a user subscribes to a discussion via email in "ASAP" mode (one of the subscription mode choices), then they will get an email notification of every message posted. If the "-fetch" flag is added to the metadotd.pl invocation, and a dedicated "discussions" email account set up as described in the Configuring Metadot section, then the email notifications will be configured so that if the user replies to a discussion message, the reply will be "pushed" back into the discussion next time the metadotd.pl script runs.

More specifically, the notifications will contain a "reply-to" field configured so that if the user replies to the message, it will be sent to the dedicated "discussions" account, with identifying information about the discussion and message encoded as part of the "to" information in the reply. Then, the metadotd.pl script will pop the discussions account, process the replies according to their 'to' fields, and publish the content of the replies as new messages in the given discussion.

If a user reply contains attachments, only the first text attachment, or the first html attachment if no text attachment exists, will be used as the content of the new discussion message.

Notes: A limitation of this feature is that the host name used in the dedicated discussion email address must also be the server from which the account email is popped. It is not currently possible to specify a separate pop server for the account.
In addition, it appears that there may be a problem in using this feature from a hotmail account. The "name" as well as the actual email address in the reply-to field of the notification message must be retained in the user reply message. It has been reported that mail sent from hotmail accounts does not always retain the "name" information.

Testing the installation

To test the installation, go to the /metadot directory. First, make sure that all your .pl scripts are executable by the 'group' of the Apache Server. You can do this by typing:

chmod 755 *.pl

Next, run the index.pl file on the command line :

    $bash > perl index.pl

For Windows, similarly invoke 'perl.exe index.pl' from the command line. You may need to include the full path to the perl exec.

You should see some raw html sent to STDOUT. If there are any problems with missing Perl modules, or misconfiguration, you will see an error when you run the script.

Now bring up the Metadot start page by accessing index.pl from your web browser:

    http:///metadot/index.pl

Configuring Metadot Portal Server

Once you can get to the Metadot front page with a browser, there is some Metadot configuration required.

If you are running multiple virtual servers (beta), then you will need to go through the following configuration process for each server-- each has its own database in which its configuration information is stored. In particular, you will need to make sure that you create separate 'images', 'skins', 'private' and 'public' directories for each server (see below). You will also need to create a separate "discussions" email account for each virtual server (see below).

  • Unless you are upgrading from a previous version of Metadot, Install the default sampledata files from the tarball. In /sitedata are three subdirectories: private, public, and skins.
    The private directory is the starting version of Metadot's access-controlled uploads directory. Make sure the private directory is a non-web-accessible location. Change its permissions so that it is writable by the web server process owner. For apache, this will typically be either "apache" or "nobody".
    If you are upgrading your portal data from Metadot version 4.0 or higher, then you will need to install a copy of your pre-existing 'private' directory rather than the default private data directory. (Upgrading from a very old version of Metadot will require copying the contents of a different directory to your private directory. See the Upgrade document for more information).

    The public directory contains the starting data for Metadot's public uploads directory. Make sure the directory is aliased to /public in your httpd.conf file. (If you are upgrading your data from a recent version of Metadot that supported the /public directory (version 4.6.1 or higher), then copy the contents of your pre-existing /public directory instead of using the default data. See the Upgrade document for more information).

    The skins directory contains the starting data for Metadot's skin uploads directory. Make sure the directory is aliased to /skins in your httpd.conf file.

  • The default out-of-the box password for the Admin is "123456". In your browser, go to the Metadot home page. In the upper right corner click on "Login". This will take you to the login screen. Log in as 'admin' using the default '123456' password. This will take you back to the main screen. [Note: If you are using the Konqueror web browser, then it has been reported that you may see an error screen the first time you log in. If you see this, then just go back and then click on 'Home'].
  • Go to the bottom of the page and click "Enable Editing". This will enter edit mode, which will cause the page's edit controls to become visible.
  • Go to the "Manage.." pulldown menu, and select "Config". This will take you to the main system management page. Click on the "show System Params" link.
  • Set 'absolute path for private file upload directory' in the configuration page
    to point to the private directory you created as instructed above. Ensure that this directory is unreachable by the web server, in order to maintain privacy of your data. Make sure this directory exists before you start running the Metadot server. Make sure also that the directory is writable by the apache process owner. This is necessary because the server cgi processes will need to add files under this directory.

    Again, if you are updating from a previous version of Metadot, you will need to copy your own existing files into the private directory -- see the "Upgrade" document.

  • Still at the "show System Params" page, if you want to enable Metadot's email-to-discussion functionality, then edit the values of these three variables: Subscription/Discussion account name, host name, and password. They must be set to define an existing account that can respond to POP3 protocol.
    If you don't want to use the email-to-discussion feature, change all three parameters to be blank rather than their example values.
  • Still at the "show System Params" page, show the default settings to reflect your hostname, mail server, proxy (if necessary), and any other parameters.
    Pay particular attention to the "Root Domain Name" and "Script Basename" fields. These should include the hostname your users should use to reach your metadot installation.

  • Change the password for the Admin user (the site's admin account). Do this in the following manner:
    1. Log in as admin, as described above.
    2. Go to "Manage..."->"My Profile". This will take you to the edit profile page for the admin user.
    3. Change the admin password and save.

Now you may configure Metadot's look and feel. When in edit mode, click on "Manage.." -> "Style & Color". Here you may show the site theme or define the headers and style sheet for your installation.

If you wish to authenticate against an LDAP server, click on "Activate LDAP Authentication" in "admin".

Notes:

  • From the Manage..->Config page (available to Admins only), the "View system status" link will not provide useful information on a Windows machine.
  • From the Manage..->Config page: the "View environment variables" link will generate a hard-to-read page that includes a lot of HTML fragments. This is due to the fact that some of the Portal's instance variables include HTML.

Configuring Single-Signon (SSO) authentication

Metadot is capable of integrating with Single-Signon (SSO) authentication systems which insert variables into the HTTP header to identify the user. Compatible SSO systems include RSA ClearTrust™ and Netegrity SiteMinder™.

To configure Metadot Portal Server to work with an SSO system, first protect the portal's URLs via the SSO system's entitlement management interface. You should test to make sure that the URL's are protected before continuing. Also, make sure that your SSO solution is inserting a usable HTTP header variable that can be used to identify the user. You can confirm this by temporarily placing the file /bin/env.pl into your metadot directory, and invoking this script from a web browser.

Once you have verified that the server is protected, you will need to make the following modifications to metadot.conf (the default metadot.conf file contains these entries, commented out.):

# use the following to enable single-signon (SSO) authentication
registration_type = FlexRegister
user_type = SingleSignonUser
authenticator_type = HeaderBasedAuthenticator
session_handler_type = HeaderBasedSessionHandler
sso_login_url = (specify your SSO login URL here)
sso_logout_url = (specify your SSO logout URL here)
authentication_header_variable = (specify the SSO header variable here)
disable_selecting_registration_modules_from_GUI = 1

 

Note that you have to specify the following:

  • The login URL used by your SSO system. For example, RSA ClearTrust™ uses /cleartrust/ct_logon.html as its default.
  • The logout URL used by your SSO system. For example, RSA ClearTrust™ uses /cleartrust/ct_logout.html as its default.
  • The name of the HTTP header variable to be used to identify a user. For example, RSA ClearTrust™ uses CT_REMOTE_USER as its default.

 

When users enter a Metadot portal, they will be authenticated by the SSO system, and forwarded to the portal server. The portal itself will not know the user's details unless they have registered onto the site. Unregistered users will be handled anonymously. When you register a user on the site, you will notice that a password is not required, and in its place is an input field for the SSO login ID. Enter the user's login identifier here to associate a Metadot portal user with an SSO login.

At this point, the admin user will not be able to login, because the admin user record is not yet associated with an SSO ID. To resolve this, execute the following SQL against the Metadot database:

  update users set ldapdn='(insert the admin SSO ID here)' where email='admin';

 

Because Metadot Portal Server generates its URLs dynamically, a portal must be protected in its entirety; it is not possible to reliably protect only certain portions of the site. Therefore, a portal that is integrated with SSO cannot have any truly anonymous users.

Currently, a Metadot portal integrated with an SSO system does not handle the user's custom start page. This is because this page only applies after login, and the user does not log in directly to the Metadot portal.

MetaDot Documentation

The Metadot documentation can be found in /doc/md_guides. Copy or move the contents of this directory to a web-server-accessible location if you wish to make the documents available to your users.

Back to top.

More documentation...

The complete user, designer and programming documentation can be found at www.Metadot.com.

Please go to the Metadot forum to get install advise from the community (again at www.Metadot.com)

The Metadot team can also help you install your server for a modest fee.

Please let us know your feedback and suggested improvements on this install documentation.

Thank you for supporting open source software.

 

-- The Metadot team