This chapter describes the MineSet extensions that are provided to let you create or view visualizations and/or interact with MineSet over the web.
MineSet Web extension allows visualizing files and data generated by MineSet software over the Web. This can be done in two ways.
MineSet mtr extension
MineSet mtr extension lets you place MineSet configuration, schema and data files into an archive file, which can be embedded in a web page as an html tag. Once the user clicks on the hyperlink in Netscape, the browser automatically invokes the mineset_weblaunch program. This brings up the MineSet visual tool. The machine that the browser is running on must have the MineSet client software installed.
MineSet Remote View
MineSet Remote View extension allows machines that do not have MineSet software installed to view visualizations through the Web. This is done via two cgi scripts that are included with the MineSet software distribution. The cgi scripts must be configured properly and installed in the Web Server machine. The cgi script rview_file.cgi must get called from a .html file with a MineSet visual tool file as an argument. The cgi script rview_dir.cgi provides the client (user who accesses the script) with a list of available visualizations. The user then can select any file via multiple popup menus and click on the invoke button to launch the MineSet tool.
All MineSet Web Extension files are located in the /usr/lib/MineSet/www directory, which contains three subdirectories.
Script | Purpose |
|---|---|
This program configures the httpd server. Use it to configure the server and the MineSet Remote View Program. If the web server is a remote machine, copy this file along with mineset_wsf.tar to the remote machine. | |
This program configures the Web browser (Netscape). Use it to configure the client. | |
This program is invoked by the web browser (Netscape). It un-archives the mtr file and brings up the appropriate viewer. | |
This program creates one or more mtr files from files created either by Tool Manager or created manually. The mtr file is sent over the network and is used by mineset_weblaunch to invoke MineSet visual tools. | |
This is a tar file of various files needed by mineset_webinstall_server. If the web server is a remote machine, copy this file along with mineset_webinstall_server to the remote machine. |
File | (continued) Purpose |
|---|---|
This file provides an index of all the mtr files supplied with MineSet. | |
rview_file.html | This file illustrates how you should embed hyperlinks to invoke mineset_rview on files and directories. |
adult-salary.eviviz.mtr | mtr file of /usr/lib/MineSet/eviviz/examples/adult-salary.eviviz. |
nl.births.mapviz.mtr | mtr file of /usr/lib/MineSet/mapviz/examples/nl.births.mapviz. |
company.scatterviz.mtr | mtr file of /usr/lib/MineSet/scatterviz/examples/company.scatterviz. |
cars-dt.treeviz.mtr | mtr file of /usr/lib/MineSet/treeviz/examples/cars-dt.treeviz. |
cars-odt.treeviz.mtr | mtr file of /usr/lib/MineSet/treeviz/examples/cars-odt.treeviz. |
churn-dt.treeviz.mtr | mtr file of /usr/lib/MineSet/treeviz/examples/churn-dt.treeviz. |
File | Purpose |
|---|---|
*.treeviz.* | Treeviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.mapviz.* | Mapviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.eviviz.* | Eviviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.scatterviz.* | Scatterviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.ruleviz.* | Ruleviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.dtableviz.* | Decision Table configuration and data files to be dynamically indexed by rview_dir.cgi. |
*.clusterviz.* | Clusterviz configuration and data files to be dynamically indexed by rview_dir.cgi. |
During the MineSet client installation the client part of the web extension is automatically installed under most circumstances. To see whether it was automatically installed run the following command.
sh -c "grep mineset /usr/local/lib/netscape/mime.types > /dev/null ; echo $?" |
If the output is 0 then you don't need to do the client installation. If the output is not 0 then you need to install the MineSet web-client extension. A program is provided for the MineSet Web installation. Before you start the installation you must make sure that MineSet Client is installed in the machine you're trying to configure. If it is not installed please install the MineSet software before you try to configure the MineSet Web Extension.
To configure the client, run the following command.
cd /usr/lib/MineSet/www/scripts ; ./mineset_webinstall_client |
The program prompts you for the location of the files mailcap and mime.types. After you provide the correct names, the program adds the corresponding entries to the files.
A program is provided for the MineSet Web installation. Before you start the installation you must make sure the following software, listed below is installed. If you are not familiar with the details contact your system administrator or webmaster and request that the installation be done for you.
For MineSet Web installation to work properly, you need
a Netscape browser
an httpd server
The server can be running on either the local machine or a remote machine. You must know:
the name of the machine on which your httpd server runs, and
the directory where the publicly accessible .html files are stored
Typically the files are located under /var/www/htdocs. The machine name is included between http:// and the first /. If you are accessing files by using http://some-machine.xxx.com/file.html, then some-machine is the name of the machine, and xxx.com is the domain name. An httpd daemon must be installed and running on some-machine.
You also must know where the httpd configuration files are stored in the server. If you are running the Netscape fast-track server, the configuration files usually are in /usr/ns-home/httpd-machine/config, where machine is the name of your machine. If you are running a version of ncsa-httpd or apache, the files might be located in /usr/local/etc/httpd/conf or /var/www/server/conf. If you are not sure where the config files are located, contact your system administrator or webmaster.
Once you know where your Server configuration files are located, you need the following two files to perform the installation
mineset_webinstall_server
mineset_wsf.tar
A script is provided with MineSet that helps with the MineSet installation. Since configuration of Web Servers varies from machine to machine, the program prompts you for the location of files. It tries to make a reasonable guess and provides defaults; however, it is better if you know where the files are located before you supply them to the program.
To start the installation, enter the following
cd /usr/lib/MineSet/www/scripts ./mineset_webinstall_server -s |
You are prompted for the location of your server mime.types file. Once you give the correct file name, it adds an entry and tries to restart the httpd daemon. If it can not restart your daemon, you must do it manually. If you're not sure about how to restart the httpd daemon, ask your system administrator or webmaster.
First copy over the following two files to the server
mineset_webinstall_server
mineset_wsf.tar
Once you're copied them over, cd to the directory where you copied the files. Then start the installation by entering
./mineset_webinstall_server -s |
It prompts you for the location of your server mime.types file. Once you give the correct file name, it adds an entry and tries to restart the httpd daemon. If it can not restart your daemon, you must do it manually. If you're not sure about how to restart the httpd daemon, ask your system administrator or webmaster.
For MineSet mtr extension to work, you must have MineSet software installed in your machine or the machine where the Netscape browser is installed. MineSet mtr files are archives of MineSet files generated by the Tool Manager or created manually. Creating an mtr file is very easy. Once created, it can be used as a hyperlink in an html page. The mtr files are very effective in sharing multiple visualizations over the web, eliminating the need for attaching huge files in mails, remote copies, or file transfers (ftp).
Since mtr files are in a compressed format and use the underlying http protocol, the transfer of an mtr file is very fast and does not require a cumbersome setup on the part of administrators.
An mtr file can be created in the following ways.
From Files created by Tool Manager
Once you have launched a tool from the Tool Manager, go to the directory from where you launched the Tool Manager and invoke mineset_makemtr using the name of the file(s) as the arguments. For example, if you have launched the Tree Visualizer and the Rule Visualizer from Tool Manager, then to create mtr files use the following command.
% mineset_makemtr foo.treeviz foo.ruleviz |
This creates two files called foo.treeviz.mtr and foo.ruleviz.mtr.
Mapviz files with .gfx extensions
If you have generated a Mapviz visualization that uses the .gfx extension, you must use the -f option of mineset_makemtr, and mention all the files that you want to include in the archive. For example, you can use the following command
% mineset_makemtr -f sales.mapviz sales.mapviz.schema sales.mapviz.data sales.hierarchy sales.gfx |
From Files not created by Tool Manager
If you've created some files without using Tool Manager, you still can create a mtr file from those files. You must use the -l option of mineset_makemtr. Suppose you want to create a mtr file from the MineSet scatterviz example directory, use the following command.
% mineset_makemtr -l /usr/lib/Mineset/scatterviz/examples/company.scatterviz |
Creating an mtr file from given files
Under certain circumstances, you might want to generate an mtr file while bypassing the checks performed by mineset_makemtr. If the checks are not performed, you are not guaranteed that the mtr file will work. You must check its usability by launching it from the web. You also must use the -f option of mineset_makemtr. Suppose you want to create an mtr file from the following files: foo.treeviz, foo.treeviz.schema, and foo.treeviz.data, then use the following command.
% mineset_makemtr -f foo.treeviz foo.treeviz.schema foo.treeviz.data |
Unlike the other options, this one can create only one mtr file.
Creating a hyperlink to the mtr file
After the mtr file is created, it should be moved to the directory containing all your .html files. For Netscape to launch an mtr file, you can invoke it directly by entering
http://yourserver/directory/foo.treeviz.mtr |
in the Netscape Location window; or you can make a link to it from a page by adding the following line in the .html file for that page.
<A HREF="foo.treeviz.mtr">foo.treeviz.mtr </A> |
After you launch a visualization via the Web browser from an mtr file, a temporary directory is created to store the files. These files are deleted after the visualization tools are launched. If you want to save these files, set the environment variable MINESET_MTR_FILE_SAVE to TRUE; mineset_weblaunch then prompts you if want to save or delete the file. If you click Save, the files are saved; otherwise, they are deleted.
MineSet remote view lets you view MineSet visual tools over the web on any UNIX platform and on PCs. The X Server running on the UNIX machine must be OpenGL-enabled. The PCs must be running an OpenGL-enabled X server, such as HummingBird Exceed 3D. You also should have:
Perl version 5.002 or greater installed on your (server) machine
the CGI.pm module version 2.35 or greater. The CGI.pm module is included with the MineSet distribution and is installed in the proper place during Remote View Installation.
First you must copy over mineset_webinstall_server and mineset_wsf.tar to the machine on which you are going to install Remote view. To do this, enter
% cd /usr/lib/MineSet/www/scripts % ./mineset_webinstall_server -r |
You are prompted for the location of your Perl binary, the Perl library and your Perl version. It provides reasonable defaults. If the default is correct, you can hit Enter to install MineSet Remoteview in the proper place. If you are not sure about some of the answers, ask your system administrator or webmaster.
The rview_dir.cgi program that is supplied with the MineSet distribution is generic and must be configured properly. By default, it works only for example files installed under /usr/lib/MineSet/www/examples. Here are the steps you must follow to configure rview_dir.cgi.
Rename the rview_dir.cgi program
Copy the program and rename it with a unique suffix, such as rview_<login>.cgi where <login> is your login name. Since rview_<login>.cgi indexes one directory at a time, you must have multiple copies of the script with the $DIR entry set to a particular directory to have multiple directories indexed. To set the $DIR entry properly, edit the rview_<login>.cgi program, and look for the following line
############# EDIT THE LINE BELOW ################ $DIR="/usr/lib/MineSet/www/rview_dir" ################################################## |
Replace /usr/lib/MineSet with the full pathname of the directory that will contain your visualization files. This directory must be available and readable by the user id (uid) under which the httpd daemon is running. Suppose your files reside in /usr/people/jdoe/mineset_files, then the $DIR entry in rview_jdoe looks like
############# EDIT THE LINE BELOW ################ $DIR="/usr/people/jdoe/mineset_files" ################################################## |
There are several other options that you can set in both rview_dir.cgi and in rview_file.cgi.
Variable (continued) | Purpose |
|---|---|
$BODY_FILE | Default is /usr/lib/MineSet/www/examples/rview_file_body.txt. This file contains the text that will be displayed when the cgi script is invoked. This file can contain embedded html tags. |
$PR_KILL | Default is OFF This variable specifies whether a visual tool invoked by the user will get killed after a certain period of time. This is a useful feature to avoid overloading the server. To turn this feature on, set $PR_KILL="ON". |
$TIMEOUT | Default is 10 minutes If $PR_KILL is "ON" then the processes will get killed after this number of minutes. |
$LOGGING | Default is ON This variable, if set to "ON, " provide detailed logging information. The information is in the following format. display user time program filename where display = name of the display the user entered user = name of the user if available time = time the program was launched program = name of the launched visual tool filename = name of the file that was viewed |
$LOGFILE | Default is /usr/tmp/rview-logIf $LOGGING is ON then the logfile where the entries will get recorded is specified in $LOGFILE. The log file should reside in a secure place. The file must be writable by the userid under which the cgi scripts are run. This is generally nobody. |
$THIS_URL | Default is http://localhost/cgi-bin/rview_dir.cgiThis entry should be set to the full URL entry an user uses to access the script. |
$RESTRICT | Default is OFF This is available only in rview_file.cgi. If it is on, files only in the directory $RESTRICT_DIR are shared. If $RESTRICT is set to ON and $RESTRICT_DIR="public_html, then files residing in public_html for any user can be accessed over the web. This is for security reason; you can turn it off if you are sure there are no confidential files in your directory. |
$RESTRICT_DIR | Default is public_html This entry should be set to a directory name where users store their.html files. |
rview_dir.cgi is invoked in the following way
http://yourserver/cgi-bin/rview_dir.cgi |
When invoked, rview_dir reads the text from the file specified in $BODY_FILE; it then creates a web page with popup menus and an Invoke button for each of the visual tools. A user can choose any file. Clicking on the Invoke Viztool button invokes the selected visual tool.
The rview_file.cgi takes a file name as an argument so once the script is installed properly in cgi-bin it can handle any request. The user does not need to change the script, only enter the location of the file in a .html file. All the variables (listed above) that are set in rview_dir.cgi are supported in rview_file.cgi. A single file can embed links to multiple visualizations via different submit buttons. A sample file, rview_file.html, is included with the distribution. It is located in the /usr/lib/MineSet/www/examples directory. For each visual file you embed, there must be two entries. If you want the user to see the visualization generated by the Scatter Visualizer on the iris dataset, add the following lines to a .html file
<INPUT NAME="View Scatterviz" TYPE="hidden" VALUE="/usr/lib/MineSet/examples/iris.scatterviz"> Clicking on the following button will bring up a view of the iris dataset. The tool that will be launched is scatterviz. <INPUT TYPE="submit" NAME="button" value="View Scatterviz"> |
For the script to work properly, the quoted string after the NAME= entry on the first line must be exactly equal to the quoted string after the value= entry on the last line. For example, the entry View Scatterviz appears both after the <INPUT NAME= entry in the first line, and <INPUT TYPE="submit" NAME="button value=" in the fourth line.
Also ensure that
the following line appears in the .html file
<form method=post action="/cgi-bin/rview_file.cgi"> |
you have a text box to which the user can set the DISPLAY. For example
DISPLAY <INPUT TYPE="TEXT" NAME="DISPLAY" SIZE=30> |
you add a line asking the user to give the program access to the Xserver. You can put the following lines in your html page
Since the visual tools will run on this server, you need to grant us access to your DISPLAY. You can do this easily by executing the command <b>xhost + machine</b> |
Replace "machine" with the name of the machine on which the cgi script resides.
The easiest way to create a customized .html file that includes all of the above is to copy rview_file.html and edit it as necessary.
It is very important to understand the security implications before installing MineSet Web Extensions. The following security concerns should be addressed before you install the web extensions.
When you publish an mtr file, the files that are included in it are sent to the client and can be saved by the user.
For rview_login to work, you (the client) must use the command xhost + machine. This allows the server to use your X display and compromises security. This is a limitation of the X protocol and not of MineSet Web Extensions. If you enter the command xhost + machine to invoke a visual tool, then xhost - machine as soon as you quit the MineSet visual tool.
Most MineSet visualization tools support an -execute option in the configuration files. Double-clicking on an object executes the command listed in the -execute option. This can be used maliciously to embed arbitrary commands in the configuration file, which then are triggered when a user double-clicks on an object. To prevent this, a warning message appears, asking whether the user really wants to execute this command. This feature can be turned off by setting the environment variable MINESET_IGNORE_WARN_EXECUTE to TRUE. Set this variable only if you're going to launch mtr files from trusted machines.