W2H: Installation Guide

Software requirements

What is needed on the server side to use the W2H interface: If you plan to further develop this product, in particular if you wish to extend W2H's understanding of the GCG/WPI configuration files or the EMBOSS ACD files, you will need also On the client side your users must have

The Installation Step By Step

The installation steps below contain the examples assuming that everything is installed in the subdirectory called w2h. This assumption is only for demonstrating various commands and the name w2h is in no case mandatory. But if you use it you will have to do less changes in the configuration files and in the documentation files.

In the following examples we assume a location of your http server as /usr/local/etc/httpd/. We also assume that you have basic knowledge how to configure your http server.

  1. Unpacking: Decompress and detar the distributed package. You will get a README file, and a subdirectory w2h. Move this directory to the place of your choice. It doesn't need to be directly in the http visible space because in the following steps you will create symbolic links.

  2. Tell the http server about W2H's location: The w2h directory has several subdirectories. Now, link them to the http visible space by symbolic links:

    ln -s /whatever/w2h/htdocs /usr/local/etc/httpd/htdocs/w2h
    ln -s /whatever/w2h /usr/local/etc/httpd/cgi-bin/w2h

    Note: Instead of using symbolic links you can define aliases in the server configuration. But, the W2H distribution contains a number of symbolic links itself. If you don't allow your http server to follow symbolic links for the W2H space, you must replace all symbolic links by real copies - not recommended.

    Anyway, the result is that you have a directory w2h accessible for running CGI scripts, and the subdirectory w2h/htdocs accessible for serving HTML documents.

  3. Restrict all-world access: The directory w2h with CGI scripts must be accessible only after the user's authentication. To do it, edit the server configuration file access.conf, or create a special file .htaccess in the directory w2h, depending on the policy you are using on your server. Here is an example what to add to access.conf

    <Directory /usr/local/etc/httpd/cgi-bin/w2h>
    Options Indexes FollowSymLinks
    AuthName "GCG WWW Interface"
    AuthUserFile /usr/local/etc/httpd/conf/.htpasswd
    AuthType Basic
    <Limit GET POST>
    order deny,allow
    require valid-user
    </Limit>
    </Directory>

    And here an example what to put into an .htaccess file in the directory w2h

    AuthName "GCG WWW Interface"
    Options Indexes FollowSymLinks
    AuthUserFile /usr/local/etc/httpd/conf/.htpasswd
    AuthType Basic
    <Limit GET POST>
    order deny,allow
    require valid-user
    </Limit>

    More about access configuration can be found at http://hoohoo.ncsa.uiuc.edu/ or in your server documentation.

  4. Define access: Let us continue with the access configuration of your server. You must create a password file with user names and passwords. In the example above, it is the file /usr/local/etc/httpd/conf/.htpasswd but it can differ on your server. You may also consider a possibility to use directly your /etc/passwd file for this purpose (it requires a small change of your server to understand a slightly different syntax, or regular update from /etc/passwd to .htpasswd). There is a tiny utility util.passwd provided to help with it.

  5. Compile the program setuser.c. There is no Makefile provided, simply use:

    cc -o setuser setuser.c

    Now you must become root because setuser must be a setuid program:

    su
    chown root setuser
    chgrp root setuser
    chmod u+s setuser
    exit

    Read carefully about security aspects and about the recommended location of this file. Be sure not to let it here, in the subdirectory w2h!

  6. Where is perl? All perl scripts in w2h and in some subdirectories search for perl in /usr/local/bin/perl5. This may not be the location of your perl. Therefore, run the following script to change it:
    perl util.install

    You can also investigate other options using:

    perl util.install -h

  7. Move W2H's bin: Some W2H scripts are in a separate subdirectory bin. These scripts are not called as CGI scripts, but W2H uses them indirectly (that means they are called from other scripts). For security reasons it is recommended to move the bin subdirectory to somewhere else - and let W2H know about the new location in Cfg.pl in the variables COMAPP and SEQINFO (see next step).

    Read also comments in the file bin/w2h.com because of the security considerations.

  8. Edit Cfg.pl: Now, a hard job is coming: edit the configuration file Cfg.pl to suit your local needs. There are 6 configuration files provided in the distribution package, use that one which corresponds with your needs (rename it to Cfg.pl if necessary):

    • Cfg.pl.v10.dist is for those providing the original "GCG version 10.x" programs
      % cp Cfg.pl.v10.dist Cfg.pl

    • Cfg.pl.GCG+EGCG.dist is for those providing the GCG programs and EGCG programs:
      % cp Cfg.pl.GCG+EGCG.dist Cfg.pl

    • Cfg.pl.emboss.dist is for those providing EMBOSS programs:
      % cp Cfg.pl.emboss.dist Cfg.pl

    • Cfg.pl.emboss+GCG.dist is for those providing EMBOSS and GCG programs
      (Note: currently you can use 1 installation of W2H for both, but you need 2 URLs and 2 independent configurations)
      % cp Cfg.pl.emboss+GCG.dist Cfg.pl
      % cp Cfg.pl.emboss.dist Cfg.pl.emboss_only
      % cp Cfg.pl.v10.dist Cfg.pl.gcg_only

    Note for GCG 8 and GCG 9
    Use Cfg.pl.v8.dist (or Cfg.pl.v9.dist), rename it to Cfg.pl:
    % cp Cfg.pl.v8.dist Cfg.pl or
    % cp Cfg.pl.v9.dist Cfg.pl

    Now, open your editor and go through the file Cfg.pl and change there what is necessary. The file is full of comments and hints what to edit and why. It is written in perl but editing should be straightforward even for a non-perlist.

    Details about the graphics conversion configuration (PSCONVERT and HP2XX) are explained below.

  9. Configure graphical output:
    Note that this step can be done also later. So if it is now too confusing, skip this step and come here later.

    W2H has special support to convert graphical outputs into common formats on the web:

    1. HPGL to PNG conversion and
    2. PS (postscript) to GIF conversion.

    • PNG format:
      Note: The PNG format is not supported by older browsers (supported since Netscape 4.04 or IE 5.5)

      There is an excellent publicly available software package hp2png to convert files from HPGL format into Portable Network Graphics format (PNG).

      For your convenience, the hp2xx-png package is included in the W2H distribution, together with two other necessary library packages (libpng and zlib). Their compilation is pretty straightforward (I have put down a few hints on it in a separate file). The packages are distributed in the subdirectory graphic-viewer.

      To enable the PNG option you have to specify the name and the location of the compiled hp2xx executable in the $HP2XX variable in Cfg.pl. By the way, this graphical format is automatically disabled if you are using an older version of Netscape or IE.

    • GIF format:
      If you want to get graphical outputs in GIF format (which I recommend), you have to download and install some additional publicly available programs (which are not distributed together with W2H, but are easily available even in binary form for different platforms). Moreover, these programs are used so often that there is a big change that you have them already on your system.

      For converting color postscript output files on the fly into GIF format, W2H needs the convert utility of the ImageMagick package.

      Further you need the postscript converter ghostscript (gs) with ppmraw as one of its output devices. This can be checked with:

      gs -help

      Now make sure that gs is in $PATH you have specified in Cfg.pl. Then you have to put the location of the convert utility in the $PSCONVERT variable of Cfg.pl.

      Troubleshooting Tips:

    Wrapper script: I have received a comment from Volker Winkelmann (Winkelmann@rrz.Uni-Koeln.DE) stating that both convert and hp2xx use shared libraries, which are not necessarily installed in any default library directory. For these situations Volker suggested to write a script-wrapper setting the library path. For example you can create the following script, name it convert and put it on the path:

    #!/bin/csh
    #
    #wrapper for ImageMagick Tool's convert,
    #because Shared Libs mut be defined
    #
    setenv LD_LIBRARY_PATH /my/graphics/lib:/usr/lib:/usr/lib/X11
    exec /my/graphics/bin/convert $*
    where the libMagick.a resides in /my/graphics/lib.

    Also Aengus Stewart (aengus.stewart@icrf.icnet.uk) has suggested that compilation ImageMagick could be a tedious job (due to all the other libs that are required), so it may be better to install precompiled binaries. It worked fine for him, except that in the wrapper script (above) he also had to set DELEGATE_PATH to point to the location of delegates.mgk.

  10. Check configuration: There are two programs helping you to check whether your Cfg.pl is properly set up:

    • Start a GCG session and then start the program util.checkcfg. Perhaps you will get some hints what can be re-configured.
      (This program is a bit outdated and for GCG only.)

    • Go to your web browser and start the CGI script w2h.checkcfg. Again follow the instructions displayed afterwards.

    It is also worth to check if your system understands the setsid() function. Mostly, it does, but to be sure run util.setpgrp and check the results according to the comments in the script itself. This function is used in W2H for killing running processes. If you meet any problems, please contact me (tell me your operating system - command uname -rs, version of your perl - command perl -v, and the results of the util.setpgrp script).

  11. Install help: (only for GCG and optional) To have access to all help pages about the individual applications, you should install help using the distributed utilities nph-w2h.helpapp and nph-w2h.helpdesc. These utilities create all help pages which are later used during run time. It uses the standard red program from the GCG distribution to create easily parsable files.

    Remember that this utility uses the file Cfg.pl mentioned above, so this file must be already properly configured.

    Run this utility and see that all help files are created. It must be run within a GCG session because it uses GCG's logical naming services:

    ...start GCG session...
    ./nph-w2h.helpapp
    ./nph-w2h.helpdesc

    Note for GCG 9/10 (or for those having own help html files):
    You do not need to do it if you wish to use the native help files coming with GCG9 and later. To use them do the following:
    • Make them visible to your http server. The files are usually in gcghelp/html/unix directory. This directory must be known to your http server (either create a symbolic link, or copy it somewhere to the visible server space).
    • In Cfg.pl edit the variable GCGHELP_HTML_DIR and put there a URL of the help files (it means a URL to the directory from the previous paragraph). Remember that this directory must contain the html documents for each application, named application_name.html (in lowercases).

  12. Edit welcome page: In the distribution there is also an example for a starting page, (its name is index.html) which can help you to create your own starter. But without editing it, this page will not be able to find all its links.

    For GCG: You can also consider to copy the CGI scripts creating application help documents somewhere else, where they are still accessible and runable as CGI scripts but without authentication. Then you can call the application help pages also from a starting page (or from somewhere else) without asking users to authenticate themselves only to see the help pages. These scripts are called w2h.helplist and nph-w2h.helpapp.

  13. Reusing memory segments: (only for GCG) Very probably you can significantly improve the speed of W2H connections by making a change in the GCG start-up scipt genetics. Please, see a special document on the tableadmin program.

  14. A special document descibes how to configure a MIME types file to be able to use your specialized viewers for output files. Usually, you do not need to change anything on your http server or on browser clients. So bother with it only in case you meet some problems. For example if you want to start a postscript viewer on the client side by clicking on files ending with .ps or .eps, but you always get text outputs only.

  15. There are also other specialised documents worth to read:

That's it. I hope I did not forget anything important. Please, send us reports of any bugs, problems or inconveniences during installation.

Hints & Notes:
If you are re-installing a new version of the W2H interface on the same place as the previous one (which is not unusual) you can temporary disable access for other users by setting the variable $UPDATING in the Cfg.pl file. See details there.

Peter Ernst
Last modified: Mon Dec 16 13:29:14 2002