A This is the distribution of CRINOID --- a multi-threaded Perl CGI  Server for the OSU HTTPd.    TABLE OF CONTENTS:      1. What you'll need first      2. The CRINOID processes       3. DOING THE INSTALLATION      4. EDITING CRINOID.CONFIG      5. STARTING IT UP!      6. RUNNING MULTIPLE CRINOIDs       7. Changing Configurations       8. A Typical Configuration       9. Setting up CGI scripts     10. Licensing      11. Acknowledgements     12. Change History     13. Needs Doing        1. What you'll need first: ==========================  D 0. You'll need the DEC C compiler. I'm pretty sure VAXC won't do the<     trick, and I've never gotten GNUC to work for me on VMS.  O 1. The OSU HTTP server: http://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html   E     While nearly all versions of the OSU HTTP server should work fine B     with CRINOID, if you're going to do "tricky" HTTP requests viaD     CGI...such as implementing Netscape Roaming, a patch to the fileB     [.base_code]script_cgiexecute.c may be needed.  Patch included=     with this distribution (SCRIPT_CGIEXECUTE-19990611.PATCH)   =     The patch is for OSU HTTP server version 3.3b, but almost B     certainly applies to previous 3.x releases...and perhaps laterC     releases as well.  You'll mostly need it if you're doing tricky F     stuff with methods other than the "standard" ones (GET,HEAD,POST).  K 2. Perl, preferably a recent version: http://www.cpan.org/src/stable.tar.gz   F     CRINOID requires Perl 5.003 or newer, because of the use of Embed.  @     A patch to Opcode.xs used by Safe:: is required for CRINOID.D     This patch does two things: it makes scripts running in a Safe::C     partition think that they are in "main::" (important for module B     use in scripts) and fixes a problem with _ use in scripts.  IfG     you have already patched Opcode.xs with an older patch that doesn't H     take care of the _ problem, don't worry...you'd likely only run into1     it while trying to upload files using CGI.pm.   J     The CONFIGURE procedure will try and figure out the patchlevel of yourJ     Opcode.xs and tell you if you need a patch.  If you've already patchedK     and need the _ fix, apply the new patch to a virgin (unpatched) version I     of Opcode.xs.   And if you've "installed" your Perl so that you don't L     have a copy of Opcode.xs sitting around, grab a copy from CPAN and patch     it.   M     Just make sure that after patching you do the whole "build/install" thing G     to get OPCODE.EXE into the right place in PERL_ROOT:[LIB...].  It's H     good to do a directory before and after to make sure that you've got(     a new OPCODE.EXE in the right place.  G     If you're building a fresh copy of Perl, apply the patch before the      main Perl build.  6     Opcode.xs patches provided with this distribution:F         OPCODE_500557_*.PATCH    patch for Perl v 5.005.57 and earlierD         OPCODE_500559_*.PATCH    patch for Perl v 5.005.59 and later.     (one of these *should* work for 5.005.58!)    C     To get the maximum benefit from Perl CGIs, you'll probably want .     some or all of the following Perl modules:  
     CGI.PM     MIME::Base64     Digest::MD5 
     libwww     GD
     PGPLOT  ? Please check the CRINOID web page (http://www.crinoid.com/) for ? module compatibility status, pointers to useful utilities, etc.    2. The CRINOID processes:  ========================  J     CRINOID   ---> persistent DECnet server, multithreaded, that processesC                   requests from the OSU server, divvies up the work E                   among a number of TENTACLES and manages the various 6                   processes that actually do the work.  A     TENTACLE ---> a process running in a 'user' account with Perl H                   (plus modules) pre-loaded.  Gets the request data fromF                   CRINOID, passes it into Perl and manages the various>               +-- startup/shutdown and i/o needed for the CGI.               | C               +-> the Perl code in TENTACLE is 'OYSTER'; it sets up E                   Safe:: partitions for the CGI scripts, locates them =                   sets up their $ENV, preloaded modules, etc. >                   Acts as a hard-shelled "wrapper" for a Perl.   Helper programs:  H     STUB     ---> used to start a TENTACLE in user context as a detached                   process.  J     CRINOIDLOG ---> records logging information from CRINOID and TENTACLE,J                   started automatically by CRINOID if not already present.  F There's probably a workaround for STUB, but the difficulty is that youE want user 'A' to start a detached process for user 'B', where the new F process does NOT have any extra privs.  The CREPRC system service callH lets you start processes with a different UIC, but not username; settingI the username is typically a CMKRNL call, and if you don't have privs it's  no-go.  ? The way around this is for CRINOID to start STUB; a very simple D detached process that has enough privs that it can "IMPERSONATE" theE target user and start a detached (and unpriv'ed) TENTACLE process for F that user.  You don't want to IMPERSONATE from CRINOID, since *all* ofJ the threads get the same impersonation (n.b.: perhaps changed in VMS 7.2).C You also don't want TENTACLE to have the privs to IMPERSONATE, ergo E the STUB workaround.  A kernel-mode workaround for pre-6.2 systems is L included, the configuration script will check if your system can IMPERSONATE or not.   H CRINOIDLOG was created as a separate process so that we can keep logging$ even if TENTACLE or CRINOID crashes.  D TENTACLE's that are started for a user will execute their LOGIN.COM,I so any special setup (stuff like PGPLOT setup, etc) should be done there; D it'll be a 'network' login so should be absolutely minimal for speed@ and robustness.  You can also do any "all-TENTACLE" setup in the" TENTACLE.COM file in CRINOID_HOME.  E A user with CGI's should also consider having an "OYSTER.CONFIG" file D in their home directory.  The OYSTER.CONFIG can set the logging fileD for script STDERR output, logging level, and 'Preload' Perl modules.F An example OYSTER.CONFIG is provided in the [.MISC] directory.  HavingE your script send stuff to STDERR, which then gets logged in a file is F currently one of the better ways of debugging CGIs...at least until we get TkPerl working on VMS.     3. DOING THE INSTALLATION  =========================     ! The following steps are required: G         @configure          & answer the questions (creates WWWPERL.COM G                                 and CONFIGURE.MMS, tests C-compiler and 4                                 system capabilities)I         @build              to build CRINOID,TENTACLE,STUB and CRINOIDLOG +                                 executables ?         @install            to move files to CRINOID directory, M                                 WWWPERL.COM to WWW_ROOT:[000000] (optionally)    You can then3         @build tidy     (or 'clean' or 'realclean')  to clean up the build area.   F Note that @configure and @build only create files in the CRINOID buildG directory (where CRINOID was unpacked), and @install only creates files B in the CRINOID install directory selected during @configure,  plus2 optionally adding WWWPERL.COM to WWW_ROOT:[000000]   After installation: <     1.  Move WWWPERL.COM to the HTTP server `home' directory<         (WWW_ROOT:[000000]) if not already done by @INSTALL.  G     2.  Add one or more `EXEC' rules to the HTTP server config files to H         direct appropriate URLs to CRINOID.  This is usually to be found>         in WWW_ROOT:[SYSTEM]HTTP_SCRIPTS.CONF, something like:  4 .NEXT       exec /cgi/*            0::"0=WWWPERL"nl:  B         if you're using the "metaconfig" stuff...otherwise just an  ( exec /cgi/*            0::"0=WWWPERL"nl:  F         You need an `EXEC' entry for each set of URLs that you want to)         have CRINOID handle, for example: /             exec /cgi/*       0::"0=WWWPERL"nl: /             exec /~joe/cgi/*  0::"0=WWWPERL"nl:   D     3.  Edit CRINOID.CONFIG in the CRINOID_HOME directory to set theG         mapping between URLs handled by CRINOID and the location of the E         Perl scripts, and how many processes owned by whom, etc. will L         be running the scripts.  See below (and the supplied CRINOID.CONFIG)         for more information.   H     4.  Add calls to @CRINOID_HOME:STARTUP to your code for starting theH         HTTP server on system startup, and @CRINOID_HOME:SHUTDOWN "FULL"*         when the HTTP server is shut down.  G     5.  Do a @STARTUP of the CRINOID server...this will define logicals C         and install the CRINOID processes with the privs they need.   ?     6.  Restart the OSU HTTP server to reload the config files.   I The CRINOID processes will be started when an HTTP request for one of the " CGI's that it handles is received.   Uninstallation:  ---------------   A clean uninstall is quite easy:  F     1.  remove "exec" lines in OSU HTTP config that reference WWWPERL,$         and restart OSU HTTP server.  1     2.  remove WWWPERL.COM from WWW_ROOT:[000000]   ?     3.  do a @CRINOID_HOME:SHUTDOWN FULL  if CRINOID is running   %     4.  delete files in CRINOID_HOME:e    A note about priviledges needed:  --------------------------------B A serious attempt has been made to minimize the priv's required toD run CRINOID, and to leave those privs OFF unless needed for specificE operations.  This, of course, means that changes to VMS may result inf: needing more (or different) privs than what I anticipated.  Q CRINOID:    SYSNAM                      DECNET ACPCONTROL, commands to CRINOIDLOGW2             LOG_IO,PHY_IO               DECNET I/OB             DETACH                      starting CRINOIDLOG, STUBsH             WORLD                       querying/shutting down TENTACLESF CRINOIDLOG: SYSNAM                      MBX name, etc. in system table@ STUB:       SYSPRV                      "username" impersonation!             +  IMPERSONATE [v7.2]uH             +  CMKRNL  [pre v6.2]       if sys$impersonate not availableC             DETACH                      starting detached TENTACLESc    C Some of these (The *_IO privs) were found by trial and error, sinceCI the VMS documentation was a bit vague.  They didn't need to be explicitly3. *set*, just available as an "authorized" priv.  ? It is strongly suggested that you run CRINOID from an unpriv'ed C account (and your HTTP server too) with just NETMBX and TMPMBX, andtB have the images installed with the minimal set of privs needed for
 operation.  > The one case where you can not operate like this is if you are; doing program debugging.  See the files in [.debug_support]c) of the distribution for more information.o   4. EDITING CRINOID.CONFIGe =========================p  D CRINOID.CONFIG is located in the CRINOID installation directory.  ItB tells CRINOID information about which accounts to use for startingC TENTACLE processes, and to direct URLs to the processes will handleoM requests (NOTE: reinstallation will NOT overwrite an existing CRINOID.CONFIG)i    A simple example, one would likeK         http://example.com/cgi/~joe/script1.pl      to run in JOE's accountd andrK         http://example.com/cgi/~fred/script2.pl    to run in FRED's account   B A set of TENTACLE processes running under a single account, with a> common set of privs and quotas, I call a "process group".  TheC "process groups" are set up in CRINOID.CONFIG, and their mapping toc URLs is also defined.g  F When a CGI request comes in, CRINOID determines the process group fromE the URL, then tries to find an idle process in that group, starting a D new TENTACLE process if necessary.  The request is handed off to theF idle TENTACLE, which calls its embedded Perl interpreter to invoke the) OYSTER script that actually runs the CGI.u  F You can set parameters for the process groups to determine the max/minD number of processes in that group; how many of them (max/min) can be
 idle, etc.  A This allows one to tune resource use for particular CGIs: a "high5D availability" CGI might have min_idle = 2 so that there are always a? couple of idle processes ready to process requests.   A typicaltA "user" CGI process group (used infrequently, longer response timeo: acceptable) would have max_idle = 0  and max_processes = 1  B In addition to specifically designated process groups one can also< have a "user" process group, where the username is filled inB dynamically from the URL...the CGI equivalent of /~user/stuff.htmlE processing.  Note that the individual processes that handle these CGIsD requests are kept strictly separate (JOE's processes handle requestsC to ~joe, FRED's to ~fred, etc.)  but they are handled with a commonr> set of configuration parameters.  This is implemented with the= USERGROUP statement in the CRINOID.CONFIG file; you use it touC designate a subdirectory name to look for the CGI scripts, and then)C use a ".SCRIPT" command to designate the URLs that are to be run inp the USERGROUP.  D For more details, look at the CRINOID.CONFIG with this distribution.   5. STARTING IT UP  ==================B After installing CRINOID, doing the necessary configuration of theF OSU_HTTP server, CRINOID, etc. ...then do @STARTUP in the CRINOID_HOME> directory.  This will just define logicals and install images.  D Do an HTTP request for a simple CGI with a browser...something like:   TEST.PL:       #! perl-)     print "Content-type: text/plain\n\n";a     print "I am.\n";  6 If you do a $SHOW SYSTEM you should see the following:       CRINOIDm     CRINOIDLOG*     user/CGI01       -> this is a tentacle   If you see:i     STUBxxxxxxJ or no ".../CGI.." processes, then there's some problem starting TENTACLEs.2 Take a look at the README.TXT in [.DEBUG_SUPPORT].  D As CGI requests are made, the number of TENTACLE processes will varyD according to the load. CRINOID will automatically shut down TENTACLED processes if they are no longer needed, or if they are consuming too much pagefile quota.   6. RUNNING MULTIPLE CRINOIDs:r =============================rA I've only used this for debugging purposes (so one CRINOID can be E messed with without causing problems for normal CGI requests), but ite may be more generally useful.u  G Here's how to do it: @CONFIGURE, @BUILD, and @INSTALL CRINOID as normaldE in the "primary" directory.  Then do another @CONFIGURE, specifying alC different ("secondary") directory.  Also select a different CRINOIDTF server process name ("CRINOID2") and Decnet service name ("WWWPERL2").B Instead of WWWPERL.COM being created in by CONFIGURE, WWWPERL2.COM will be created.  / @BUILD and @INSTALL to the secondary directory.w  E Copy the WWWPERL2.COM that is generated in the "secondary" @CONFIGUREaD to your OSU HTTP sys$login directory.  Then add "exec" rules in your1 OSU HTTP script configuration to invoke WWWPERL2.e   Example:F     exec /cgi/*            0::"0=WWWPERL"nl:        ( primary CRINOID)H     exec /alt-cgi/*        0::"0=WWWPERL2"nl:       ( secondary CRINOID)  C Make sure that the CRINOID.CONFIG for the secondary server does not G have any "SERVICE ..." lines.  The Decnet service name will be set from ' a logical name defined in WWWPERL2.COM.u  E You will need to adjust urls, etc.  (to handle /alt-cgi/* rather thanG* /cgi, for example) in CRINOID.CONFIG also.  % Then @STARTUP the new CRINOID server.c  > NOTE: the first CRINOID server to start (in response to a HTTP@ request) will start its own CRINOIDLOG.  *ALL* of the subsequentE CRINOID servers will use the same CRINOIDLOG process, so you may wanto> to edit the LOGGER.COM procedures in all of the CRINOID serverF directories to point them to a common log file. (See the definition of CRINOIDLOG_FILE in LOGGER.COM).e  = The @SHUTDOWN procedure will only stop the associated CRINOID B (as of v0.4-1). But @SHUTDOWN FULL will also stop CRINOIDLOG, evenA if other CRINOID servers are still running. So if you're going to E do a SHUTDOWN FULL, do a SHUTDOWN of any other CRINOID servers first; 9 having CRINOIDLOG missing causes problems for the server.o  @ If you need to use different OYSTER.CONFIG's for the two serversE (probably a good idea), simply edit the OYSTER. script in the CRINOIDtJ home directory and change the line (near the beginning) to something like:#     $ConfigFile = 'Oyster2.config';I     7. Changing Configurations:u ===========================nC While scripts and OYSTER.CONFIG files are automatically reloaded if A they are changed, this is NOT the case for changes to system-wide ! programs and configuration files.y  C If OYSTER. or SCRIPT.PM are changed all TENTACLES should be killed,sE but it does not require a restart of CRINOID.  See KILL_TENTACLES.COMiA in the [.misc] subdirectory of the distribution for a handy-dandyC TENTACLE killer.  B If CRINOID.CONFIG or the executables are changed, then the CRINOID< server should be shut down (@SHUTDOWN, use @SHUTDOWN FULL ifE executables or logging options were changed).  If the executables aree= changed, you need to do a @STARTUP to get the new executablesD# installed in place of the old ones.x   8. A Typical Configuration ==========================  & In WWW_ROOT:[SYSTEM]HTTP_SCRIPTS.CONF:     ...C,     exec /cgi/*            0::"0=WWWPERL"nl:     ...   " WWW_ROOT:[SYSTEM]START_SERVER.COM:  8     $ here = f$parse("Z.Z;",f$env("procedure")) - "Z.Z;"     $ x = f$setprv("all")      $ set def 'here'     $ set def [-]s     $ base = f$env("default")C     $ set def 'here'     $!7     $ F = F$SEARCH("DISK$SYSTEM3:[CRINOID]STARTUP.COM")A     $ IF F .NES. "" THEN @'FV     $ @'here'HTTP_Startup HTTP 'base'http_server.log/9 'here'HTTP_MAIN.CONF "80" "443"     $!     $ x = f$setprv(x)w
     $ exit   CRINOID.CONFIG:t     #O@     # very simple, only user-scripts like   /cgi/~fred/tryit.cgiH     #                          mapping to   disk:[fred.www-cgi]tryit.cgi     #      LOGLEVEL          4s     USERGROUP         /www-cgi     .SCRIPT           /cgi/~*t     .processes        0 3t     .PAD              0 1      9. Setting up CGI scripts: ==========================  C You can use "standard" (if there is such a thing!) CGI scripts withc CRINOID...two examples:e       #! perls)     print "Content-type: text/plain\n\n";W     print "hello, world!\n";         #! perlS     use CGI;     $q = new CGI;n&     print $q->start_html('hey there');(     print $q->h1('This is a big title');     print $q->end_html;-     Script reusability ------------------A To improve the performance of your scripts, you should write themvB so that they are "reusable"...typically that is when you don't useD variables before they are initialized, since the value might be leftI over from a previous run. (And don't count on them being there, either...TD two sucessive requests might go to two different TENTACLE processes)  F You should be able to run your script interactively with the "-w" flag set:     $ perl -w myscript.cgi$ and not have any warnings generated.  H When your script is well behaved, then put in a line near the beginning:       $CRINOID::Reuse = 1;  K This will tell the server that the script can be reused, at a great savings7+ in memory use and with much faster startup.   D If your script is edited, the server will detect the fact and reload the newest version.E   File extensionso --------------- C You can specify which file-extensions to use for CGI scripts in thea OYSTER.CONFIG file:dH     Suffixes    .pl .cgi .  # only allow NAME.pl NAME.cgi  NAME. scriptsE The URL still has to have the appropriate extension, but requests for 4 files without an acceptable suffix will be rejected.             /cgi/mystuff/testit.cgi9          /cgi/mystuff/testit2           -> for "testit2."    Directories and PATH_INFOn -------------------------y  F If you have subdirectories of your "cgi directory" you can put CGIs inC those subdirectories, and the URLs will need the subdirectory name:   J     /cgi/mystuff/testit.cgi         -maps to->  disk:[user.cgis]testit.cgiN     /cgi/mystuff/test/test2.cgi     -maps to->  disk:[user.cgis.test]test2.cgi  J The server normally searches for CGI scripts "depth first", so if you have  ! URL:  /cgi/mystuff/test/xyz/test1   ?         [user.cgis.test.xyz]test1.        <-- this one gets run :         [user.cgis.test]xyz.                this isn't run0         [user.cgis]test.                       "  M You can alter this behavior by setting the "NoDescend" flag in OYSTER.CONFIG;LI if "NoDescend" is set, subdirectories will *not* be searched for scripts.   I When a script is found, all of the URL to the right of the script name isD available as $ENV{'PATH_INFO'}:R  4 URL:       /cgi/mystuff/test/xyz/something_else/here script:    [user.cgis.test]xyz.  path_info: something_else/here     Modules and @INC ----------------I Modules that are frequently used, especially if used by multiple scripts, J can be pre-loaded to reduce script startup time.   Some script pre-loadingK is done in OYSTER, but the scripts preloaded in OYSTER are really a minimaleF set that (because of the way Perl loads them) *must* be preloaded if aK script is going to use them.  An example is modules that are linked to Perlr statically.r  F In OYSTER.CONFIG you can add "Preload" lines that will preload modules for your scripts:      Preload     Digest::MD5y     Preload     PGPLOT     ...t  K Note that there are some modules (such as CGI) that you should NOT preload.eL The CGI module has such tricky symbol export logic (and tends to keep memoryH of what it was doing) that preloading just won't work properly.  ModulesH that are preloaded are shared among ALL the scripts being run in a givenI TENTACLE process, so modules that remember stuff from one run to the nextt! should be preloaded with caution.p  L If you preload a module you should also "use" it in your script...it doesn'tG hurt in terms of memory or startup time, and it may help initialize therH module properly....as well as making the script so that it can be tested interactively.  I When you try to "use" modules, sometimes it will be necessary to set @INC 5 appropriately.  The directories on the @INC list are:t           CRINOID_ROOT:[LIB]0         ..the usual Perl directories for @INC...*         the 'home' directory for the CGI'sA         directories specified by OYSTER.CONFIG  "AddINC" commandsoD         directories specified by  #! perl -I ...  line in the script  D The script "home" directory is either the base directory for the CGID (i.e., something like disk:[user.cgis]  ) or the directory specified* in the "HomeDir" command in OYSTER.CONFIG.  D If you need to add directories to @INC for multiple scripts, use theD AddINC command.  If it is just one or two scripts, then on the first. line of the script you can put something like:#     #! perl -Idisk:[myincdir.stuff]x     ...rest of script...H Just like you would do from a command line (except you don't need double quotes around it).   Debugging, Errors, etc.t ------------------------C Several OYSTER.CONFIG commands are useful for debugging and keepingo tabs on your scripts:T  F     Errlog  oyster.log       # log file (in sys$login dir, by default)?     LogLevel 3               # log level, 1=critical...5=babble=W     MaxLogfileSize    50000  # create new logfile if old one is too big (size in bytes) ?     MaxLogfileVersions  5    # purge logfile versions /keep=...bD     MaxRunTime 100           # max time a script can run, in secondsD     Debug m                  # Perl debug flags  (e.g.,  $Perl -Dm )  M Use the "debug" command cautiously, some debug options are extremely verbose..  M In addition you can specify the "-w" option on the #! line to turn on warningeI messages.  This isn't terribly useful for _running_ CGIs, but is good forU testing.  H The script STDERR output will be sent to the Errlog file that you set inI OYSTER.CONFIG.   If you don't set an Errlog file, the STDERR output winds = up in CRINOID.LOG where it's much more difficult to decipher.   C Sometimes there'll be a nasty, BUG in your CGI.  When that happens, F CRINOID will send back an error message...which may or may not display? properly depending on what stuff has been sent back previously.N  ) For example, having a text error message:        Error in ... at line ...  6 doesn't do much good when the script first writes out:       Content-type: image/gifd  < At that point it's best to look in CRINOID.LOG for guidance.  B If you want to customize the pages generated for errors, there's a& OYSTER.CONFIG command that might help:  R ErrorHTML   disk:[dir]errorpage.html    # use this for error messages from OYSTER.  G If an error occurs, OYSTER will grab the file specified and substitute:i  - #   <!--#error-->   ->  text of error messagen& #   <!--#script-->  ->  name of script  0 before sending it out as a "text/html" document.     GET, POST, PUT --------------  F When you use a CGI to handle an HTTP request, you really have a lot ofE control over what happens.   For example, it's easy to implement yourLC own authentication system....just check $ENV{'HTTP_AUTHORIZATION'},rF maybe redirect to a "https:" protocol, check cookies, etc. ...and send1 a "401" if you need the user to enter a password.i  E You can also implement (using $ENV{'REQUEST_METHOD'}) the POST or PUTSD methods...POST gives you form data that you can read from STDIN, PUT! does the same for file uploading.   B There's some "nonstandard" methods that Netscape uses to implementC roaming access:  MOVE (renames a file) and DELETE.  I've managed totE do roaming access with a CRINOID CGI...it works fine (even moderatelyiE fast) but your Netscape config will be messed up good if your networka9 connection goes down in the middle of an up- or download!f  F If you're interested in applications like this, please let me know and  I'll send you some example code.     10. Licensing: ===============.  @ This program is Open Source, under the general terms of the PerlC Artistic License (http://language.perl.com/misc/Artistic.html) withaD one exception: Part #5: "You may charge a reasonable copying fee..."D first two sentences replaced with "You may sell this program as long= as you make available full source code and properly attribute  authorship."  = Needless to say, this program is provided "AS-IS" and with noaE warrantee of fitness, usefulness, being non-destructive, etc.  Use atN your own risk.  ? Please inform me of any fixes or modifications you make; and ifY? you want to be alerted to upgrades or bugfixes let me know thate you're using CRINOID.    11. Acknowledgements ====================  C This program owes a tremendous amount to Dave Jones and his work on M the OSU web server (http://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html).E? Astute readers of the code will notice a number of places wherel- "Dave's code" was the obvious starting point.   ; Larry Wall's Perl, of course, is a simple necessity of life 3 (http://www.perl.org), as well of CGI applications.t  ? Charles Bailey (bailey@newman.upenn.edu) provided a much-neededwD kickstart to the development of this program, with his hints on what5 would work best for good Perl CGI performance on VMS.s  F The bugs of course, are mine, all mine.  But you're welcome to as many as you want to take away!=   12. Change History:r ===================a7     0.1  early  1998?   initial version (named `SQUID') ;     0.2  fall   1998    major rewrite of thread/piping coder9     0.25 spring 1999    logging removed from main program :                         many thread/network timing changes4                         config file capability added1                         OYSTER config files added-,     0.3     9 Dec 2000  first public releaseD     0.3-1  10 Dec 2000  from Emanuele Ruffaldi <pit@sssup1.sssup.it>=                         need _PTHREAD_USE_D4 flag for VMS 7.2nI                         destroy_STRING needs to return a value, all caseshG            16 Dec 2000  Fix to STUB.C so that it can compile on AXP foreC                         VMS 7.2 (extra unused params in IMPERSONATEaE                         system service call). STARTUP.COM modified toaH                         check for and set IMPERSONATE priv if available.O     0.3-2  13 Jan 2000  from Dr. Martin P.J. Zinser <ZINSER@sysdev.exchange.de>r?                         VMS::Filespec needed preload, in OYSTER J                         also copy TZ logical into OYSTER Safe:: partitions@                         SHUTDOWN.COM get the single quotes right<                         INSTALL.COM  location of WWWPERL.COMF                         CONFIGURE.COM ask about 'installlib' directoryO     0.3-3  20 Jan 2000  from Dr. Martin P.J. Zinser <ZINSER@sysdev.exchange.de>v8                         SQUID, ERRLOG, LOGGER found someI                         picky, picky DECC warnings, all about my abuse ofc1                         signed vs. unsigned ints."K     0.4     4 Feb 2000  rename to CRINOID; $SQUID::Reuse still works, addedu-                         $CRINOID::Reuse also.uC                         EXC_HANDLING.H/DECC bug check functionalitybI                         during config;  Various config and com file fixessA                         Define licensing to be applied to CRINOID =             8 Feb 2000  Mods to OYSTER: oyster.config can setfD                         "suffixes" to allow only some file suffixes,F                         set HomeDir directory to chdir to when runningN                         scripts, set NoDescend to NOT search in subdirectories7                         for a script URL with PATH_INFOh;                         Generate fake PID in $$ for scriptsL  E     0.4-1  10 Feb 2000  CRINOID.COM, SHUTDOWN.COM modified to make its7                         easier to run multiple servers. F                         Added KILL_TENTACLES.COM to shut down TENTACLE)                         processes easily.c  A                         SCRIPT.PM improved script error-handling,oD                         implement -I -D  and -w flags on CGI scipt's*                         leading `#!'  line?                         (options not fully parsed, needs work).a>                         Extensive change in script compilationF                         compilation (eliminated the 'do $file' stuff),=                         and module sharing.  It's faster now.   C                         Script timeout capabilities added in OYSTERcB                         and SCRIPT.PM, controlled by MaxRunTime in%                         OYSTER.CONFIGl  F                         mod to CRINOID.C to remove trailing slash fromF                         CRINOID.CONFIG bindir's. It was making probems;                         for scripts, giving double slashes.h  G                         Added OYSTER script-lookup caching, so we don'taH                         have to walk the CGI directory tree for a script)                         we already found.n    F     0.4-2  14 Feb 2000  Modifications to CRINOID.C, SCRIPT.C, SCRIPT.HC                         and CRINOID_TYPES.H to support multihoming. F                         After a ".SCRIPT" directive in CRINOID.CONFIG,H                         one can add a "..LOCALHOST hostname" to restrictG                         the script URLs to only those from a particularpG                         localhost name (as specified in the SERVER_NAMEOF                         parameter generated by the OSU server).  SinceG                         the search for a matching URL in CRINOID.CONFIGOE                         proceeds from the "top down", one should have.3                         "more specific" URLs first.   K                         If no ..LOCALHOST directive is given, any localhost](                         name will match.  J                         Added ErrorHTML parameter to OYSTER.CONFIG so thatF                         one can use a user-generated "CGI error" page;H                         substitutes on the fly for the error message andF                         script name.  See [.MISC]OYSTER.CONFIG-EXAMPLE  F                         Various OYSTER script/path/cache lookup fixes.  K     0.4-3  15 Feb 2000  mods to CONFIGURE.COM, INSTALL.COM, and STARTUP.COMRL                         to make multi-server operation easier.  In CRINOID.CC                         get DECNET_SERVICE_NAME from logical if notaE                         defined in CRINOID.CONFIG.  The "WWWPERL.COM" 5                         (or whatever, name defined byd>                         DECNET_SERVICE_NAME) sets the logical.  D                         Added ..BINDIR command for CRINOID.CONFIG asB                         an option for the .SCRIPT command, so thatC                         script URLs in the same process group don'ts/                         have to share a bindir.   E                         Note that the "USERGROUP" *does* have to havenC                         a common BINDIR, in the sense that the samesD                         subdirectory of a user's SYS$LOGIN is commonE                         for all.  Can add process groups for specific ;                         users before the USERGROUP command.m  K                         Mods to CRINOID to separate out the part of the URLCC                         that doesn't map to directory structure andhD                         make it available to OYSTER (SCRIPT_PREFIX).E                         Mods to OYSTER to strip the prefix when doing 1                         tree-search for a script.d  E     0.4-4  16 Feb 2000  fixed an annoying bug with bindir finding fortC                         usergroups in CRINOID.C.  And another smallnD                         (non-harmful) bug in OYSTER's url parsing is                         fixed.  G                         First attempt at "non-PERSONA" capabilities forSD                         STUB.  Checks for PERSONA system services inH                         CONFIGURE.COM. If there's no PERSONA, we have toE                         change the USERNAME in the PCB and JIB systemcE                         data structures with a little CMKRNL routine.d  F                         We get some MACRO->C definitions converted forF                         $JIBDEF and $PCBDEF and set the "username" andE                         uic for the detached process started by STUB.p  G                         Modified STARTUP to look for CMKRNL priv neededn-                         for non-Persona STUB.n  J                         Tried the non-Persona version of STUB and it seems%                         to work okay.s  )            17 Feb 2000  Minor doc changese  G            15 May 2000  Martin Zinzer <zinser@sysdev.exchange.de> fixedV+                         typo in STARTUP.COMt  C     0.4-5   6 Jul 2000  move creation of WWWPERL.COM to build phasel  K                         change to SCRIPT.PM to fix package/sub name findingnQ                         problem reported by Mike Marmor <mike.marmor@reuters.com>p  L                         Prompted by Mike Marmor's suggestions, OYSTER.CONFIGJ                         can now have "addinc DIR1 [DIR2 [DIR3...]]" lines,M                         that will append to the @INC used to look up modules.r  F     0.4-6   20 Jul 2000 Added AddENV and ExportENV to OYSTER.CONFIG toF                         import and export from logicals to script %ENVI                         This can also be used to export TZ to the process '                         logicals table.r  G                         Change to CONFIGURE.COM to look for .h files ineL                         Perl_root:[000000...], and to print more informativeL                         message when PERL_SETUP.COM is not found.  Change toG                         INSTALL.COM to set up Perl before installation.n  L                         Note: should use CGI.PM v2.68+, fixes some CGI::CarpN                         and file uploading problems, but CGI::Carp still callsG                         exit, resulting in an error.  Submitted a minoreI                         patch to CGI.PM 2.68 to fix file upload: it seemsrD                         that file tests on _ don't work right in CGI&                         environment...  J                         Added support for __DATA__ and __END__ in scripts;I                         note that this is NOT parsed internal to Perl, soPL                         you have to treat it gently:  put __DATA__ on a line;                         by itself if you want it picked up.hN                         (E.g. /^\s*__DATA__\s*$/)  Which is good style anyway.  M                         The "read position" in the file is maintained between M                         script invocations (if you're using reusable scripts) L                         so you can read the data the first time and cache it3                         in a persistant variable...e  F                         Added MaxLogfileSize and MaxLogfileVersions toG                         OYSTER.CONFIG to control OYSTER log generation. H                         Added dump of module namespace to logfile to aid-                         in preload debugging.   G                         Minor change to OYSTER and SCRIPT.PM to prevent J                         variables persisting when a script is modified and!                         reloaded.T  H                         Tracked down at least one timing-related ACCVIO:G                         process idling, disconnecting, then DELPROC was H                         triggering it.  A trivial fix, but hard to find!  K                         Added an overload to "exit" for scripts and cleanedSG                         up messages.   Note that to make CGI::Carp worktJ                         properly an overload to CGI::Carp::exit was added,J                         and a tricky "init_stash()" call so that the stashE                         for (root)::CGI:: and (root)::CGI::Carp:: arev<                         initialized into the Safe partition.  I                         Don't try to preload CGI (or any CGI::* modules), G                         there's too much stuff that shouldn't be sharede2                         between different scripts.  3     0.5     25 Jul 2000 update docs, bump version # A                         Fixed use of filetests on _ in scripts... F                         change in Opcode.xs was needed, so will update                          patches.  @                         Check Perl_root:[lib...] permissions andC                         check for Opcode.xs patch during CONFIGURE.oB                         Generated new Opcode patches based on Perl$                         version #'s.  E                         created [.debug_support]test_global.pl to get G                         a list of global symbols, added save/restore in D                         SCRIPT.PM, also sets $^T and $0 for scripts.  ;     0.5-1   28 Jul 2000 minor changes for VAX compatibility      13. Needs Doing: ================
 Bug Fixes:  	 Upgrades:      o Documentation!.     o A better syntax for CRINOID.CONFIG? -or-4       a Perl script to help generate CRINOID.CONFIG?:     o get TKperl working, so can use for debugging scripts9     o an intelligent model of #procs/#idle vs. hit rates? ;     o Add process quotas etc, that haven't been implementedtD     o MAJOR PROJECT: implement CRINOID as MST extension to OSU HTTPd1     o Taint check CGI scripts with -T on #! line? 8     o use lockmgr to deal with CRINOIDLOG start/restart?@       -or- put CRINOIDLOG back into CRINOID as a logging thread?A     o IMPERSONATE per-thread and eliminate STUB for VMS 7.1? 7.2?     , --Chuck Lane  lane@duphy4.physics.drexel.edu