Channel Archive CGI Setup

Prerequisites

Web Server

Like any other CGI tool, the CGIExport tool for the Channel Archiver is a plug-in for a web server. This means you have to have a running web server and you need to know how to configure it. Usually this includes need for the root password (Unix) or Administrator priviledge (Win32).
In here I can only provide examples on how to configure some web servers (Apache web server, MS Internet Information Server/MS Personal Web Server).
If you don't understand the examples or happen to use a different server, please consider consulting the manual for your web server first.
For any useful application of this CGI plugin you also have to generate web pages. Some knowledge of HTML and CGI is required: You have to understand HTML and how the web server turns a given URL into the name of an HTML file or CGI program on the disk. Visual HTML editors like Frontpage might help with the visual design of the web pages, but they are not sufficent: You have to know what the produced HTML stands for.

Access to the archive: Users, permissions, paths

The CGI Tool has to have access to the data files, either directly or via NFS, SAMBA, whatever.
Note that the web server runs any CGI program as a low-priviliged user. On Unix, that's usually 'nobody'. On Win32, it might be 'IUSR_xxx' for "Internet User on host xxx". I assume 'nobody'.
To verify archive access, become that user and try to access the data via e.g. the command-line ArchiveExport tool. On Unix, try "su" to become root, then "su - nobody" to logon as just that. Note the '-' in "su - ...." which makes you run through the full login sequence.
A special problem: The 'nobody' user might not have PATH, LD_LIBRARY_PATH etc. configured, so it helps to build the CGIExport tool without using shared libraries to simplify matters. Or copy the shared libraries into the directory where the CGIExport executable resides (this is what I do for the Win32 DLLs). Or configure the web server to set LD_LIBRARY_PATH before executing CGI scripts (possible for the Apache web server, shown below).

GNU Plot

For the plotting to work, you need GNU Plot. The path to GNU Plot is hard-coded into the CGIExport tool at compile time, see the top-level ArchiverConfig.h.

Example Setup

The default path names are relative but fixed and have to be similar to the Test directory tree underneath the CGIExport source directory. After you changed the CGIExport configuration in <ChannelArchiver>/ArchiverConfig.h, the following might no longer work for you:

• ChannelArchiver/CGIExport/Tests/
  HTML files for accessing the CGI Tool, must be exported via WWW server.
  When producing any output, CGIExport looks for files cgi_body_start.txt and cgi_body_end.txt.
  This Test directory is prepared such that these files contain links to additional web pages, explaining the use of the CGIExport tool to users.
  
• ..../Tests/cgi
  The executable CGI tool must be copied in here as CGIExport.cgi.
  Note the file extension, it's used in the WWW server configuration later on!
  The WWW server must allow "execute" access to this directory.
  (For Win32, the files Com.dll, db.dll and ca.dll from your EPICS/base/bin/WIN32 also have to be copied into here.)
• ..../Tests/cgi/tmp
  In here, the CGI tool creates temporary files, so you must create this directory. And the CGI program has to be able to create files in here. Remember that it's running as 'nobody'.

Make sure that the WWW server as well as CGI programs launched by it (usually running as "nobody") have access to those parts of the file system, especially check write access to ...../cgi/tmp !
To test the CGI tool, make the Test directory accessible by your WWW server and make sure that the cgi subdirectory is executable (see below for MS and Apache specifics).
There are simple Perl scripts cgi/Hi.pl and cgi/env.pl to debug your WWW setup.
You don't need perl to use the CGIExport tool in the end.
The scripts are meant to test your web server setup because many CGI extensions are written in Perl and therefore every web administrator should be able to help you with this:
If installed and configured correctly, you can access "http://<your host>/archive/cgi/Hi.pl", e.g. "http://localhost/archive/cgi/Hi.pl" to verify that

1. Your web server is running at all
2. You managed to configure it correctly in order to execute the perl-CGI scripts

Try "http://localhost/archive/cgi/env.pl" to see under what environment the CGI tools run.
The next step is to test if you can execute the CGIExport tool:
Try " http://localhost/archive/cgi/CGIExport.cgi.
You should see some HTML page, no error message.

Usage

When called with COMMAND=HELP like this:
http://<your host>/archive/cgi/CGIExport.cgi?COMMAND=HELP"
the CGIExport Tool will display the commands and parameters that it understands.
You will see that the CGI parameter "DIRECTORY" defines the archiver directory file, often called "freq_directory". According to the CGI specification, this means that you can either prepare an HTML form with a "DIRECTORY" field to pass that parameter or define an HTML link to "http://your_host/archive/cgi/CGIExport.cgi?DIRECTORY=%2Fsome%2Fdir%2Ffreq_directory"
Note how a directory file of "/some/dir/freq_directory" gets transliterated, replacing '/' by the ASCII hex code %2F according to the CGI specification.
The example web page ChannelArchiver/CGIExport/Tests/Default.htm shows some links that call the tool with a specific archive directory, channel list, commands etc.
When your WWW server setup was successful as explained in there, you should be able to point your web browser to http://localhost/archive/Default.htm and see that initial test page.

Troubleshooting

Ideas on what to test:

• Web Server: Is it running at all? Try "netstat -a" and check if anyone is listening on TCP port 80.
• Web Server: Can you access the web pages, e.g. the "Default.htm" file? If not, check how the web server maps "virtual directories" to disk files.
• Web Server: Can you access the CGI directory, i.e. read it and are the files executed as programs?
• If the perl scripts respond OK, try the env.pl program. This is not required, you don't need perl for the CGIExport program, but the env.pl script can help with debugging the settings for the "nobody" user.
• If the perl scripts respond OK but CGIExport.cgi doesn't: Can you execute it as "nobody" from the command line? Are shared libraries missing which happen to be in your path as USER=<you> but not when you are USER=<the web server=nobody>?
• Can the cgi tool (that is: the pseudo-user that runs it) access the data files?
• Can the cgi tool create the temporary files needed for the plots?
• Can ... launch GNU Plot?

Microsoft IIS (Windows 2000)

1. Install the IIS from the Win2000 disk. It shows up under additional products. I picked the Common Files, the Documentation, the WWW server and Personal Web Manager. You don't need SMTP, FTP, FrontPage extensions etc. When looking at http://localhost for the first time, you get linked to the documentation.
2. Configure under "ControlPanel"/"Administrative Tools"/"Computer Management":
   Right-click on "Default Web Site", select New Virtual Directory. Name it "archive", browse to ChannelArchiver/CGIExport/Test, select only "read" for access permissions.
   http://localhost/archive should now lead to an archive test page, the links on there don't work until the next step is completed.
3. Right-click to properties on the "cgi" directory under the "archive" virtual entry created in the previous step. Uncheck the "read" permission, select "Execute Permissions" "scripts and executables", "Application Protection" to "High".
4. If you have Perl: Click "Configuration", "Add", set executable to e.g. "c:\sys\perl\bin\perl.exe %s" for the extension ".pl". This should allow to browse http://localhost/archive/cgi/env.pl which might help in debugging CGI problems.
5. While ".pl" had to be configured, I could not find a ".cgi" entry but executables ending in .cgi seem to be lauched without further configuration when "scripts and executables" were selected for the directory.

Microsoft Personal Web Server

1. Export the Test directory as e.g. "/archive",
2. Export Test/cgi directory as "/archive/cgi" and make it executable
3. Modify registry to allow perl scripts (useful for debugging, not essential for CGI tool):

   [HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3Svc\Parameters\Script Map]
             c:\sys\perl\bin\perl.exe %s %s;
   	

Apache Web Server

Add to end of /etc/httpd/httpd.conf :

  #Added for CGIExport Test:
  #
  #Uncomment these (usually found earlier in this file)
  #if you want perl support:
  #LoadModule perl_module modules/libperl.so
  #AddModule mod_perl.c
  #
  #Note that without special settings,
  #apache does not follow symb. links,
  #so these names have to be 'real':
  Alias /archive "/home/Kay/Epics/extensions/src/ChannelArchiver/CGIExport/Tests"
  <Directory /home/Kay/Epics/extensions/src/ChannelArchiver/CGIExport/Tests>
  Order Allow,Deny
  Allow from All
  </Directory>
  # Make /archive/cgi executable, allow Perl:
  # (this requires the above settings to activate mod_perl)
  AddHandler perl-script .pl
  AddHandler cgi-script .cgi

  # Note that we set LD_LIBRARY_PATH!
  <Directory /home/Kay/Epics/extensions/src/ChannelArchiver/CGIExport/Tests/cgi>
  SetEnv LD_LIBRARY_PATH /cs/epics/R3.13.3/base/lib/Linux
  PerlHandler Apache::Registry
  PerlSendHeader On
  Options +ExecCGI
  </Directory> 

Start/stop on an older Linux:
/etc/rc.d/apache {start|stop|status|restart|reload}

From RedHat6.x on:
/etc/rc.d/init.d/httpd {start|stop|status|restart|reload}

Error Log:
cat /var/log/httpd.error_log

---