Cray Inc. Welder s-2340-21 User's Manual
Contents
1. pl2prod dmp search 6 5 Moving CrayDoc craydoc pm Functions used by all the CrayDoc CGI scripts interactive pm Common functions for the install script and the cdadmin tool An optional script that allows the user to request a printed copy of a Cray publication via e mail This script requires that your CrayDoc server have network access to a SMTP server that can relay e mail to Cray All the software releases for which you have installed documentation This file must be readable and writable by the executing CGI UID see Section 2 3 2 page 9 A database that maps all man page product names and versions to their respective file path abbreviations This file must be readable and writable by the executing CGI UID see Section 2 3 2 page 9 The directory for the CrayDoc search engine it contains all the searching indexing and index data files See Section 6 3 page 27 for more details If at any point you need to move your CrayDoc installation to a different machine with a different operating system you can preserve your existing documentation without being forced to reinstall from the original CDs You should be able to use the tar command to bundle up all your existing files move them to the new location extract them and then change your craydoc config file to reflect the new configuration You will then need to reindex the search engine because the databases it creates are platform specific S 2340 212. 29 CrayDoc Installation and Administration Guide 6 6 Upgrading from version 1 0 30 This section guides you through the process of upgrading your CrayDoc server software from version 1 0 to 2 0 The safest way to upgrade your server software is to rename your existing CGI and HTML directories the values of ScriptAlias and DocumentRoot respectively and create new directories for your 2 0 files with the same names as the old directories You can then test the installation and if necessary revert to the old 1 0 directories if you enounter problems with the new 2 0 installation Using this method the URL remains the same for your users Caution Several of the installed CrayDoc 2 0 files require hard coded path values which the install script automatically performs for you If you install CrayDoc manually you must edit these files by hand The values that require hard coded paths are indicated with an HTML comment tag lt somevalue gt where somevalue is an absolute path The path values depend on your craydoc config configuration The files that require these values are craydoc cgi glossary cgi manpage_display cgi in ScriptAlias all the administration tools including cdadmin and the main index html file in DocumentRoot You should have a copy of your existing 1 0 craydoc config file available for reference Procedure 1 Upgrading to CrayDoc 2 0 1 Rename your existing ScriptAlias and DocumentRoot
3. Example http craydocserv username or http craydocserv craydoc Complete URL for your CGI scripts Your CD mount point Turned on by default This option generates a dynamic home page for each book If commented out links to manuals will default to the Apache DirectoryIndex setting usually index html or index htm See Section 6 1 page 25 for more on other options for the book home page Set to frontpage html by default This is the main home page for CrayDoc You can change this setting to point at a different HTML page or customize frontpage html for your site see Section 4 2 4 page 22 Turned on by default You may turn this off by not installing the orderform cgi script and by commenting out this option S 2340 21 Installing CrayDoc 4 Once you have created your craydoc config file copy it to the correct location cp craydoc config ScriptAlias Now you are ready to copy the necessary files from the CD 4 2 3 Copying and Unpacking If installing CrayDoc manually you must copy the necessary files from the CrayDoc CD to the correct locations as indicated in your craydoc config file To make this easier use the same installation map that the install script uses install dmp This file is located at the root level of the CD It is written in the format of a Perl hash The map is a list of the file paths in relation to the root level of the CD You can interpret where to copy each file this way
4. page 18 for more information about the craydoc config file 6 At this point your 2 0 server software is installed correctly and you need to move your existing documentation to the new DocumentRoot location Example 4 Moving the manuals directory prompt gt mv var www docs 10 manuals var www docs You should now be able to point a web browser at your original CrayDoc URL and view the documentation you already had installed in version 1 0 If any of the links are broken verify that the new 2 0 craydoc config settings are correct 31 Index A administration tools 25 Apache source code 2 B Berkeley Database source code 3 a cdadmin tool 26 Compatibility 1 D Dumper pm module 3 H Hardware requirements 4 I installing local custom documents 27 S 2340 21 M Manual installation craydoc config 18 map of file locations 21 Mode Shared 8 Stand alone 7 P Perl source code 2 S Security 8 permissions 9 11 suEXEC 9 Sendmail pm module 4 Software requirements 2 33
5. Many other recent Linux distributions come with all of the required packages be sure to check the version numbers of your Apache and Perl installations against the requirements in Section 1 2 page 2 CrayDoc Installation and Administration Guide 1 2 Software Requirements 1 2 1 Apache 1 2 2 Perl CrayDoc requires the following software all of which are included on the CrayDoc Documentation Library CD 1 Apache version 1 3 x or later 2 Perl version 5 005 or later version 5 6 1 recommended 3 DB_File Perl module version 1 7 2 or later 4 CGI Perl module 5 Dumper pm Perl module 6 Sendmail pm Perl module for the optional Order Form function The version of Perl on the CrayDoc CD includes the correct versions of all modules needed for CrayDoc There is a copy of the Apache version 1 3 20 source distribution and an INSTALL file on the CrayDoc CD Documentation for installing and configuring Apache is freely available on the Internet as well Apache powers 60 of the web servers on the Internet The Apache web site is http httpd apache org If you decide to compile Apache yourself from source see Section 2 3 page 8 If you already have Apache installed see Chapter 3 page 11 for help configuring it for CrayDoc The source distribution of Perl version 5 6 1 is included on the CrayDoc CD along with the Perl INSTALL file Note Be sure to make a note of your Perl installation path for later use in configuring
6. The HTML Interface Cray Documentation 5 Man Pages Books Administration 6 Tools The cdadmin tool The Search Engine Contents of ScriptAlias Moving CrayDoc Upgrading from version 1 0 Procedure 1 Upgrading to CrayDoc 2 0 Example 1 Example 2 Example 3 Example 4 Moving the manuals directory Index Page 12 13 15 15 16 16 18 21 22 23 23 24 25 25 26 27 28 29 30 30 30 30 31 31 33 S 2340 21 Preface This publication describes CrayDoc 2 0 release and installing and administering CrayDoc and Cray documentation Ordering Documentation S 2340 21 To order software documentation contact the Cray Software Distribution Center in any of the following ways E mail orderdsk cray com Web http www cray com craydoc Click on the Cray Publications Order Formlink Telephone inside U S Canada 1 800 284 2729 BUG CRAY then 605 9100 Telephone outside U S Canada Contact your Cray representative or call 1 651 605 9100 Fax 1 651 605 9001 Mail Software Distribution Center Cray Inc 1340 Mendota Heights Road Mendota Heights MN 55120 1128 USA CrayDoc Installation and Administration Guide Conventions The following conventions are used throughout this document Convention command variable user input manpage x vi Meaning This fixed space font denotes literal items such as file names pathnames man page names command n
7. books also known as manuals and man pages Books are available in both HTML and PDF formats and are delivered on the CrayDoc CD Man pages are available in both formatted also known as catman ASCII and HTML formats Catman ASCII man pages are normally installed automatically along with your software on your Cray system and are accessed with the man command HTML man pages are a new feature of CrayDoc version 2 0 and are delivered on the CrayDoc CD We recommend that when you install Cray documentation on your CrayDoc system you choose to install both man page and book packages for each software release so that the complete set of documentation for each release is available through the CrayDoc user interface You may choose to use the documentation without installing the CrayDoc server software but you will not be able to search all the HTML files without the server software Whether you choose to install the documentation on a CrayDoc server or simply view it locally from the CD you should understand the organization of the documentation Man pages and books are structured differently so this chapter discusses their organization Man pages describe uniquely identifiable components of your software such as commands libraries and system calls Each software release may contain one or more sets of man pages which are grouped together into packages A package is a set of documentation that supports a specific release of a software product fo
8. by logging in to the CrayDoc server and typing ps ef grep httpd See the Apache documentation for more troubleshooting help When you have successfully installed Apache you can configure it for use with Stand alone mode Section 3 1 page 12 Shared mode is the most flexible installation option because it allows your CrayDoc installation to coexist peacefully with other users of the Apache web server However Shared mode requires a more intimate understanding of Apache configuration See Section 3 2 page 12 for more details Security issues also are important to consider when deciding whether you install in Stand alone or Shared mode Stand alone mode offers more security but requires that CrayDoc be the main use of the Apache web server Shared mode offers more flexibility but requires coordinated effort between the Apache and CrayDoc administrators and careful attention to file system permissions A thorough understanding of file system permissions is essential for installing CrayDoc successfully in Shared mode S 2340 21 Preparing for Installation 2 2 3 1 suEXEC The suEXEC is one option to consider for Stand alone mode If you are concerned about the possibility of someone abusing your Apache installation via the CrayDoc system and you are installing CrayDoc in Stand alone mode you may want to consider compiling Apache with the suEXEC option This option allows CGI commands to run under a different user ID th
9. carefully about the environment in which you intend to use the CrayDoc system CrayDoc requires the Apache web server Your site may already be using the Apache web server CrayDoc is designed to integrate smoothly with already existing installations of the Apache web server Refer to the mode that is best suited to your particular needs and environment Stand alone CrayDoc has a dedicated Apache installation This scenario allows for optimal security and performance See Section 2 1 page 7 for installation instructions and more information Shared CrayDoc shares an existing Apache installation This scenario allows CrayDoc to coexist with other users of the Apache web server and it requires the involvement of the administrator of your existing Apache installation See Section 2 2 page 8 for installation instructions and more information You must also consider security issues when selecting a mode see Section 2 3 page 8 2 1 Stand alone Mode S 2340 21 The Stand alone installation scenario allows for the most control over CrayDoc security and performance In this scenario the Apache web server is configured with CrayDoc as the primary user Examples of this scenario include e An unused Linux compatible computer that is an extra PC that you want to devote to being a CrayDoc server e Root access to a computer that is not currently running an Apache web server For this documentation we will assume you have a Red Hat
10. case you need to compile and install the Berkeley Database files which include the required Perl DB_File module See the documentation in this directory for more details or see the Berkeley Database web site at http www sleepycat com ASCII file with legal information If you install CrayDoc manually read this file ASCII file with general information and a how to for the anxious to install Directory containing source code for the Apache 1 3 20 distribution See the included documentation or the Apache web site http httpd apache org docs for more information Perl script for use with the install script Directory containing the CGI scripts HTML interface and supporting files 17 CrayDoc Installation and Administration Guide install manuals manpages Perl Perl_mods releases Bourne shell script for automated installation of CrayDoc This script simply finds your Perl location and then calls configure pl Directory containing all the Cray book files Directory containing all the Cray man page files Directory containing source code for Perl 5 6 1 This version of Perl includes all the modules required for CrayDoc Directory containing the Data Dumper pmand Mail Sendmail pm Perl modules Directory containing ASCII file s of the packages included on your CrayDoc CD Each file contains necessary information about each of the documents included with the package Once you have determi
11. install CrayDoc under a user s account or in a subdirectory under the main Apache DocumentRoot You may also consider using a VirtualHost directive in Apache in conjunction with either of the above two options See the Apache documentation for pros and cons of each scenario Because of the infinite possible Apache configurations this document does not provide examples for every possible scenario The install script will attempt to S 2340 21 Configuring Apache 3 accommodate your particular configuration Section 4 1 page 15 but you may find that you need to install CrayDoc manually Section 4 2 page 16 Just as with Stand alone mode the easiest way to install CrayDoc is with the included install script See Section 4 1 page 15 3 3 Apache Tips and Troubleshooting Some common troubleshooting tips for the httpd conf file for installing in Shared mode follow CrayDoc requires Apache ExecCGI permissions for the CrayDoc ScriptAlias directory see Section 4 2 2 page 18 and Section 2 3 2 page 9 for more details The ScriptAliasMatch directive is an easy way to do this If for example you want to install CrayDoc under a user s public_html cgi bin directory add the following line to your httpd conf file in the mod_alias section ScriptAliasMatch cgi bin pathtouserhome 1 public_html cgi bin 2 A slightly more secure option since only the user may use it to execute scripts is the ScriptAlias di
12. CrayDoc Perl versions 5 6 0 and later include the required Perl modules so if you are using Perl version 5 6 0 or later you should not need to install them separately To verify your Perl version type the following at a shell prompt Perl v S 2340 21 Introduction 1 If you have Perl installed on your system you can type the following at a shell prompt to test if you already have a module installed For example to verify the presence of the DB_File module type find Perl e print INC name pm print grep DB_File If you are using a nonstandard Perl installation or you are missing a required module you can either upgrade your Perl installation Perl 5 6 1 is included on the CrayDoc CD we recommend you upgrade or compile and install the modules individually see the CrayDoc CD for the source code and documentation for the required Perl modules 1 2 3 Berkeley Database and DB_File Module 1 2 4 The CGI Perl Module Installation documentation for the Berkeley Database is available from the source distribution on the CrayDoc CD The DB_File Perl module is available within the Perl DB_File directory of the Berkeley Database source distribution on the CD Read the README files within the BerkeleyDB directory for installation help Note It is not enough to compile the Perl DB_File module You must have the Berkeley Database libraries installed as well See the Berkeley Database documentation f
13. CrayDoc Installation and Administration Guide S 2340 21 2001 2003 Cray Inc All Rights Reserved This manual or parts thereof may not be reproduced in any form unless permitted by contract or by written permission of Cray Inc U S GOVERNMENT RESTRICTED RIGHTS NOTICE The Computer Software is delivered as Commercial Computer Software as defined in DFARS 48 CFR 252 227 7014 All Computer Software and Computer Software Documentation acquired by or for the U S Government is provided with Restricted Rights Use duplication or disclosure by the U S Government is subject to the restrictions described in FAR 48 CFR 52 227 14 or DFARS 48 CFR 252 227 7014 as applicable Technical Data acquired by or for the U S Government if any is provided with Limited Rights Use duplication or disclosure by the U S Government is subject to the restrictions described in FAR 48 CFR 52 227 14 or DFARS 48 CFR 252 227 7013 as applicable Autotasking CF77 Cray Cray Ada Cray Channels Cray Chips CraySoft Cray Y MP Cray 1 CRInform CRI TurboKiva HSX LibSci MPP Apprentice SSD SuperCluster UNICOS UNICOS mk and X MP EA are federally registered trademarks and Because no workstation is an island CCI CCMT CF90 CFT CFT2 CFT77 ConCurrent Maintenance Tools COS Cray Animation Theater Cray APP Cray C90 Cray C90D Cray CF90 Cray C Compiling System CrayDoc Cray EL Cray Fortran Compiler Cray J90 Cray J90se Cray J916 Cray J932 C
14. Linux 7 2 system running on an average off the shelf PC The average installation time for a new Red Hat system is about 60 90 minutes which includes the installation of Apache 1 3 12 and Perl 5 6 0 with all the necessary modules Once you have Apache and Perl successfully installed the next step is deciding where you will install CrayDoc In a Stand alone scenario it is up to you CrayDoc Installation and Administration Guide 2 2 Shared Mode 2 3 Security Issues to decide where on your file system you put the CrayDoc installation We recommend only that you verify that you will have enough space on your file system to accommodate the Cray documentation see Section 1 3 2 page 5 Verify that your Apache web server is running by pointing a web browser at your CrayDoc server If you are using a web browser running on the CrayDoc server machine you should be able to point your browser at http localhost and you should see the Apache test page or whatever home page you may have replaced it with If you are using a web browser running on a machine other than the CrayDoc server you should be able to point your browser at the host name of your CrayDoc server For example if your CrayDoc server s host name is craydocserv you should be able to see the Apache test page at http craydocserv If you cannot see the Apache test page you probably have a problem with your Apache installation Verify that the ht tpd daemon is running
15. ames and programming language elements Italic typeface indicates an element that you will replace with a specific value For instance you may replace filename with the name datafilein your program It also denotes a word or concept being defined This bold fixed space font denotes literal items that the user enters in interactive sessions Output is shown in nonbold fixed space font Brackets enclose optional portions of a syntax representation for a command library routine system call and so on Man page section identifiers appear in parentheses after man page names The following list describes the identifiers User commands System calls Library routines Devices special files and Protocols File formats Miscellaneous information o N FO FP WN FS Administrator commands S 2340 21 Preface Reader Comments S 2340 21 Contact us with any comments that will help us to improve the accuracy and usability of this document Be sure to include the title and number of the document with your comments We value your comments and will respond to them promptly Contact us in any of the following ways E mail swpubs cray com Telephone inside U S Canada 1 800 950 2729 Cray Customer Support Center Telephone outside U S Canada Contact your Cray representative or call 1 715 726 4993 Cray Customer Support Center Mail Software Publications Cray Inc 1340 Mendota Heights Road Mendota Heigh
16. an the user ID of the calling Apache web server You can read the Apache documentation on the suEXEC option at http httpd apache org docs suexec html Here is an example configure command line to compile in suEXEC support on a Red Hat Linux system prompt gt configure with layout Red Hat enable suexec suexec uidmin 100 suexec gidmin 100 suexec docroot home httpd html suexec caller www Caution Be certain that the suexec caller value equals the User directive value in your Apache httpd conf file CrayDoc relies on file system permissions for its security so if you have set up CrayDoc according to the Stand alone instructions in Section 3 1 page 12 you probably do not need to compile the suEXEC option However if you do compile the suEXEC option into Apache your CrayDoc permissions will need to be set accordingly See Section 2 3 2 page 9 for more information 2 3 2 Understanding permissions S 2340 21 You should only give as much permission as is absolutely necessary for CGI scripts to be executed and for HTML and PDF files to be read This means that you should know first of all which user and group ids UID and GID your CGI scripts execute with when they are called by the Apache server The executing UID or GID must have permission to execute your CrayDoc CGI scripts and read your CrayDoc library files In a Stand alone installation this me
17. ans you can set permissions on your CrayDoc files very tightly for example 500 if the file is owned by the executing UID In a Shared installation file permissions must be set so that the executing UID has executable permissions to the CrayDoc scripts in ScriptAlias read permissions to all the db and dmp files in ScriptAlias and read permissions to all the documents in library and manlibrary For more details on the ScriptAlias manlibrary and library variables see Section 4 2 2 page 18 CrayDoc Installation and Administration Guide Note CrayDoc 2 0 requires that all the CGI scripts and databases need only to be readable and executable by the executing UID or GID All administration is done by the cdadmin tool so the executing UID of the cdadmin tool must have write permission to ScriptAlias and DocumentRoot directories but the Apache user does not need to have write permission 10 S 2340 21 Configuring Apache 3 S 2340 21 Apache is highly configurable and your site may have special configuration needs See the Apache documentation on the CrayDoc CD or at http httpd apache org docs for more details Whether you install in Stand alone or Shared mode CrayDoc requires certain information from your Apache configuration file These settings are found in the Apache httpd conf file ServerName The name returned to the web browser by the Apache web server Example craydocserv foo com DocumentRoot Th
18. cument Root manpages TxtSearchURL ScriptURL search search pl CrayDocCGI SScriptURL craydoc cgi ManPageCGI SScriptURL manpage_display cgi GlossCGI SScriptURL glossary cgi SLibraryRoot SURLRoot manuals Icons SURLRoot img p12prod_dmp ScriptAlias pl2prod dmp maninfo_dmp ScriptAlias manpages dmp Sgloss_dmp SScriptAlias glossary dmp SSMTP localhost Here is a list of the settings required and what they mean 19 CrayDoc Installation and Administration Guide DocumentRoot ScriptAlias User Group cgi_umask html_umask URLRoot ScriptURL path2cd autohomepage splashpage orderformfunction 20 The full file path from where Apache will be serving files Example var www html The full file path where your scripts reside similar to DocumentRoot Example var www cgi Who should own all your CrayDoc scripts and files Which group all your CrayDoc scripts and files should belong to Note Your User and Group settings should be coordinated with your Apache User and Group settings so that the Apache web server has appropriate permissions to all your CGI scripts and files See Section 2 3 2 page 9 for more details The permissions in chmod numerical format of the executable scripts The permissions in chmod numerical format of the non executable files HTML PDF etc The URL in Shared mode with your specific subdirectory appended
19. directories Example 1 prompt gt mv var www docs var www docs 10 prompt gt mv var www cgi bin var www cgi bin 10 2 Create new directories with the same names as your old ScriptAlias and DocumentRoot directories Example 2 prompt gt mkdir var www docs prompt gt mkdir var www cgi bin 3 Mount the CrayDoc CD and install the 2 0 software with the install script When prompted be sure to use the same directory values that you used for your 1 0 installation For more information about the install process see Section 4 2 page 16 S 2340 21 Administration 6 S 2340 21 4 Copy your 1 0 books dmp and packages dmp files from your renamed 1 0 ScriptAlias directory to the new 2 0 ScriptAlias directory Verify that they have the correct permissions See Section 2 3 2 page 9 for more information about permissions Example 3 prompt gt cp var www cgi bin 10 packages dmp var www cgi bin prompt gt cp var www cgi bin 10 books dmp var www cgi bin 5 Open a web browser and point it at the URL of your new 2 0 installation If you can see the CrayDoc welcome page then you have installed 2 0 correctly and should proceed to the next step Otherwise verify that you have configured the 2 0 craydoc config file correctly and that your permissions are set correctly Often the Apache error log is a good place to check for error messages See the Apache documentation for how to access the error log See Section 4 2 2
20. e Ifa file path begins with htm1 copy it to DocumentRoot e Ifa file path begins with img copy it to DocumentRoot img e Ifa file path begins with modules copy it to ScriptAlias modules e Ifa file path begins with search copy it to ScriptAlias search e Ifa file path is simply a file name with no prepended path copy it to ScriptAlias e Ifa file path begins with tools copy it to your administration tool directory See Section 6 1 page 25 for more on the administration tools Caution File permissions for these files will vary according to your IN particular configuration but they should match whatever values you set in the cgi_umask and html_umask variables See Section 2 3 2 page 9 for more information Once you have copied the files to the correct locations and changed permissions and ownership appropriately you are ready to install Cray documentation Proceed to Chapter 5 page 23 S 2340 21 21 CrayDoc Installation and Administration Guide 4 2 4 The HTML Interface The CrayDoc HTML interface is mostly generated dynamically by the various CGI scripts However there are a few static HTML pages that you may edit The main one is frontpage html which is what users first see when they connect to the CrayDoc server You may edit this file to suit your particular needs using any text editor 22 S 2340 21 Cray Documentation 5 5 1 Man Pages S 2340 21 Cray delivers two kinds of documentation
21. e root path of your HTML documents ScriptAlias The root path of your CGI scripts User The name or UID under which the web server will execute CGI processes Group The name or GID under which the web server will execute CGI processes Caution The User and Group settings are very important for your installation They must refer to a real user and a real group on your system Unless your Apache installation was compiled with the suEXEC option see Section 2 3 page 8 all CGI processes will run as the user and group specified in your httpd conf file which means that the same user or group must have correct permissions to all your CrayDoc files In Stand alone mode we recommend that you create a specific system user and group for use with Apache and CrayDoc Something appropriate and easy to remember like user craydoc and group craydoc is recommended This will give you the most control and security over your installation In Shared mode you must know the User and Group settings in your Apache configuration so that you can verify that your CGI scripts are executable and your files readable by the web server For security reasons you should not make your CGI scripts world executable and depending on your particular installation you may not want to make your documentation world readable either See Section 2 3 2 page 9 for more details 11 CrayDoc Installation and Administration Guide 3 1 Apache in Stand alone M
22. estamps of all your installed documentation against the timestamp of your search index database and warn you if you have documents that are not indexed Very useful as an added precaution against forgetting to re index your search engine after installing or removing documentation 25 CrayDoc Installation and Administration Guide 6 2 The cdadmin tool 26 The cdadmin Perl script is the administration tool for your CrayDoc system Unlike CrayDoc 1 0 version 2 0 is administered entirely from the command line using the cdadmin tool For security reasons you should install cdadmin outside the ScriptAlias file path The administration password is stored in plain text in the cdadmin file so you should protect the file with tight permissions Only the user who administers the CrayDoc system should have read or execute permissions to the file You can start the cdadmin tool from the command line just like any other command path_to_file cdadmin You will be prompted to enter the administration password and then you should see this menu Please select a mode 1 Install Packages 2 Remove Packages 3 Remove a Book 4 Remove a Man Page 5 Reindex the Search Engine 6 List Installed Documents by Package 7 List All Installed Books 8 List All Installed Man Pages 9 Install Custom Documents 10 Exit NOTE This tool uses more to page results Enter mode number Note The paging tool is
23. hlighting of search results Man pages now available in HTML format Glossary of software terms available online Advanced search options This book also includes revised information in Section 6 6 Record of Revision Version Description 1 0 December 2001 Original Printing 2 0 December 2002 Updated to reflect new features in CrayDoc 2 0 release 2 1 February 2003 Updated to include changes in Section 6 6 Upgrading from version 1 0 S 2340 21 i Contents Page Preface gt Ordering Documentation a N ne ee ee er og v Conventions ho g p i e We eo ee a ce Se ee Wes ce a a Us Vino oe eh a en vi Reader Comments s ae ho o a aa o a G a a a Oe da a a A a a a G vii Introduction 1 Compatibility Software Requirements Apache Perl Berkeley Database and DB_F ile Module The CGI Perl Module The Dumper pm Perl Module Sendmail pm and Order Form Function Hardware Requirements RAM Hard Drive Space ga A A A OU Q N N NBE a Preparing for Installation 2 Stand alone Mode Shared Mode Security Issues SUEXEC oo Oo 0 ON N Understanding permissions Configuring Apache 3 11 Apache in Stand alone Mode en ah he ee ak ok teh Ge eA A ee 12 S 2340 21 iii CrayDoc Installation and Administration Guide Apache in Shared Mode Apache Tips and Troubleshooting Installing CrayDoc 4 Automated Installation Manual Installation CD Contents The craydoc config File Copying and Unpacking
24. ide The easiest way to reindex your site is with the cdadmin tool See Section 6 2 page 26 for more information 6 4 Contents of ScriptAlias 28 The following contents of your ScriptAlias directory reflect what is installed books dmp collections dmp craydoc config craydoc cgi g g lossary cgi lossary dmp manpage_display cgi manpages dmp modules The main database for all your installed books This file must be readable by the executing CGI UID see Section 2 3 2 page 9 All the Cray publication categories data which allows searching according to Intended Audience or Hardware Product This file must be readable by the executing CGI UID see Section 2 3 2 page 9 Main CrayDoc configuration file See Section 4 2 2 page 18 for more details Main CrayDoc CGI script This script interfaces with all the databases and allows you to use your CrayDoc system Glossary search and display CGI script Glossary database Man page search and display CGI script Man page database Directory for all CrayDoc Perl modules This directory contains the following modules Mail Enclosing folder for the optional Perl module Sendmail pm used by the optional orderform cgi script to send e mail to Cray CrayDB pm Functions for interacting with the CrayDoc databases CrayDocGlossary pm Functions for the glossary cgi script S 2340 21 Administration 6 orderform cgi packages dmp
25. ne S 2340 21 The CrayDoc search engine is based on the PerlFect Search 3 30 package http Perlfect com freescripts search and modified under the auspices of the GNU General Public License http Perlfect com freescripts GPL Note PerlFect is not responsible for the modifications that Cray has made to their software and will not support your CrayDoc search engine Direct any questions or concerns directly to Cray The CrayDoc search engine is highly configurable The version that is installed with CrayDoc is optimized for use with CrayDoc but you may find that you want to change some of the configuration to suit your particular needs The relevant file is located at ScriptAlias search conf pl which may be edited with any text editor Caution Modifying the conf p1 file may have lots of unforeseen consequences particularly in the time it takes to reindex your library and the speed and accuracy of your searches We suggest that you make a backup copy or comment out the original lines when you make changes so that you can easily return to a version of the conf p1 file that is known to work well with CrayDoc If you change certain settings in the conf p1 file you must reindex your documentation in order for the changes to take effect These settings are annotated as such in the conf p1 file In addition you should always reindex your library if you add or remove manuals 27 CrayDoc Installation and Administration Gu
26. ned that you have the necessary software and you have configured Apache correctly for either Stand alone Section 3 1 page 12 or Shared mode Section 3 2 page 12 you will want to create your CrayDoc configuration file copy your CrayDoc files to the correct locations and customize your HTML interface as described in the following sections 4 2 2 The craydoc config File If you install your CrayDoc software suite manually you need to create a configuration file similar to the following example 18 S 2340 21 Installing CrayDoc 4 S 2340 21 Note In Perl scripts as in shell scripts lines beginning with a pound sign are comments and are ignored usr bin Perl CrayDoc 2 0 Configuration File written by configure pl Thu Oct 31 15 00 02 CST 2002 OS Linux OSversion 2 4 7 10 Hostname somehost Perl usr bin Perl Install StandAlone CD ROM Location mnt cdrom SDocumentRoot var ww html ScriptURL http somehost foo com cgi bin ScriptAlias var www cgi bin SUser someuser Group somegroup Scgi_umask WTO es Shtml_umask WEIS Spath2cd mnt cdrom SURLRoot http somehost foo com Sautohomepage m Ssplashpage frontpage html Sorderform ves Sbooksdmp SScriptAlias books dmp Scollectionsdmp SScriptAlias collections dmp Spackagesdmp SScriptAlias packages dmp Slibrary SDocumentRoot manuals Smanlibrary SDo
27. nual Installation 4 2 1 CD Contents 16 If you decide to install CrayDoc manually either because you cannot use or do not wish to use the install script you should have a thorough understanding of how CrayDoc works and fits together We recommend that you become familiar with your Apache configuration especially the httpd conf file and that you have a good understanding of file system permissions This section describes the details of the CrayDoc components and how you can install and configure them You should read Section 1 2 page 2 Chapter 2 page 7 and Chapter 3 page 11 before proceeding any further Depending on your system you may need to be the root user in order to mount the CD At the prompt enter prompt gt mount cdrommountpoint S 2340 21 Installing CrayDoc 4 S 2340 21 where cdrommountpoint is your system s CD mount point On Linux systems this is usually mnt cdrom Change to the CD directory and look at the contents prompt gt ed cdrommountpoint prompt gt ls 1FC BerkeleyDB LICENSE CrayDoc PerlFect README apache configure pl craydoc install manpages manuals Perl Perl_mods releases The CD contains BerkeleyDB LICENSE CrayDoc apache configure pl craydoc Directory containing source code for the Berkeley Database If you are using Perl 5 6 0 or later you should not need this code Otherwise it is provided in
28. ode Usually you must be logged in as the root user to configure Apache though your particular installation may vary First make sure the Apache httpd daemon is not running prompt gt killall httpd Second edit your Apache httpd conf configuration file paying particular attention to the five settings listed at the beginning of this chapter The httpd conf file is well commented refer to it and the Apache documentation for more details Third close and save your httpd conf file and then start the httpd daemon to test your changes prompt gt httpd If you get any errors when starting your httpd daemon go back and check your httpd conf file You should now be ready to install the CrayDoc server See Section 4 1 page 15 3 2 Apache in Shared Mode 12 If you choose to install CrayDoc on a system with a pre existing Apache installation you will need to consult with your local Apache administrator about the best way to install CrayDoc Because we cannot anticipate your particular Apache configuration you should read the Stand alone mode Section 3 1 page 12 Permissions Section 2 3 2 page 9 and Manual Installation Section 4 2 page 16 sections thoroughly before attempting a Shared mode installation Once installed CrayDoc in Shared mode works the same way as in Stand alone mode but you must understand how your existing Apache system is configured in order to install CrayDoc You have two basic options in Shared mode
29. on it is on by default If it is turned on the Sendmail pm module is automatically installed for you 1 3 Hardware Requirements 1 3 1 RAM If your computer can run Perl and Apache it should support CrayDoc Your hardware needs will vary according to your environment the number of users you expect to access the CrayDoc server and what other software you are running on the computer There are two aspects of RAM use to consider when setting up your CrayDoc system e Indexing the search engine e Configuring Apache The CrayDoc search engine can require significant memory over 200 MB when indexing the manuals See Section 6 3 page 27 for more information on configuring the search engine The Apache documentation covers some aspects of improving the performance of your Apache web server See http httpd apache org docs misc perf tuning html for more information We recommend a minimum of 96 MB of total RAM for a Stand alone CrayDoc installation and 256 MB if you choose the Shared installation S 2340 21 Introduction 1 1 3 2 Hard Drive Space S 2340 21 The entire set of Cray documentation HTML and PDF versions will fit on a single CD that is less than 650 MB A standard Red Hat Linux system and a typical CrayDoc installation will easily fit on a 2 GB hard drive Take your backup system into consideration when making hard drive decisions Preparing for Installation 2 Before you install CrayDoc think
30. or more information The CGI Perl module is included with all Perl versions 5 005 and later If you do not have the CGI Perl module installed you should consider upgrading your Perl version to 5 6 1 which is included on the CrayDoc CD 1 2 5 The Dumper pm Perl Module S 2340 21 The Dumper pm Perl module is according to the Dumper pm documentation part of the standard Perl installation in versions 5 005 and later This module allows for reading and writing of the CrayDoc databases Warning A version of the Dumper pm module is included on the CrayDoc CD The included version will only work with Perl version 5 6 1 or later Do not install this version of the Dumper pm module unless you are running Perl 5 6 1 or later and have already verified that you do not have the Dumper pm module already installed See Section 1 2 2 page 2 for more on verifying your Perl modules CrayDoc Installation and Administration Guide 1 2 6 Sendmail pm and Order Form Function CrayDoc includes an optional function that allows users to send e mail to Cray requesting printed copies of manuals The Order Form function requires the Perl Sendmai 1 pm module The Sendmail pm module is not part of any standard Perl distribution and so it is included separately on the CrayDoc CD If you install CrayDoc with the included installation script see Section 4 1 page 15 you will be prompted as to whether you want to leave the Order Form function
31. page 12 for more information about these settings During the install knowing the location of your httpd conf file is necessary only if you are doing a Stand alone mode install since the install script uses this file to determine your default CrayDoc settings On a Linux system this is installed by default at etc httpd conf httpd conf and that is where the install script will look for it by default Note You will be prompted during the install process for which mode you want to use If you indicate Shared mode you will be prompted at some point during the install process for a subdirectory value The subdirectory is the value that should be appended to the ServerName for your main HTML URL This value might be a user s directory or a subdirectory under the main DocumentRoot or some other value depending on your particular Apache configuration During the install process you will be asked to verify the URLs for your CrayDoc installation Check these carefully before accepting them 15 CrayDoc Installation and Administration Guide If you want more information on the specifics of the CrayDoc settings or for help in installing CrayDoc manually without using the install script see Section 4 2 page 16 The install script will guide you through the process of installing your CrayDoc server software Once the install script completes successfully you are ready to install the Cray documentation Proceed to Chapter 5 page 23 4 2 Ma
32. r example C C 4 2 or UNICOS mp 2 0 Each man page is identified by four pieces of data name The name of the man page usually the same as the software component it documents volume number The kind of component the man page documents See the conventions section Conventions page product name Name of the product that the man page supports This usually but not always corresponds to the package name product version Version of the product that the man page supports This usually but not always corresponds to the package name 23 CrayDoc Installation and Administration Guide 5 2 Books 24 When you view man page listings in the CrayDoc user interface each man page should have both an implementation and a package name listed next to it The implementation information is the product name and version with which the man page is associated On the CrayDoc CD all the available man pages are located in the manpages directory You should use the cdadmin tool to install man pages See Section 6 2 page 26 for more information Cray delivers HTML versions of most books and PDF versions of all books Each book is identified by a publication number On the CrayDoc CD all the PDF and HTML versions of the books are located in the manuals directory in subdirectories named for the publication number of each book Books like man pages are grouped together into packages A book package is a collection of the books that
33. rayLink Cray MTA Cray MTA 2 Cray MTX Cray NOS Cray REELlibrarian Cray S MP Cray SSD T90 Cray SV1 Cray SVlex Cray SV2 Cray SX 5 Cray SX 6 Cray T90 Cray T94 Cray T916 Cray T932 Cray T3D Cray T3D MC Cray T3D MCA Cray T3D SC Cray T3E CrayTutor Cray X1 Cray X MP Cray XMS Cray 2 CSIM CVT Delivering the power DGauss Docview EMDS GigaRing HEXAR IOS ND Series Network Disk Array Network Queuing Environment Network Queuing Tools OLNET ROS SEGLDR SMARTE SUPERLINK System Maintenance and Remote Testing Environment Trusted UNICOS UNICOS MAX and UNICOS mp are trademarks of Cray Inc IRIX is a trademark of Silicon Graphics Inc Linux is a trademark of Linus Torvalds Netscape and the Netscape N and Ship s Wheel logos are registered trademarks of Netscape Communications Corporation in the U S and other countries PostScript is a trademark of Adobe Systems Inc Red Hat is a trademark of Red Hat Inc Solaris is a trademark of Sun Microsystems Inc UNIX the X device X Window System and X Open are trademarks of The Open Group in the United States and other countries All other trademarks are the property of their respective owners New Features CrayDoc Installation and Administration Guide S 2340 21 This book documents the following new features of CrayDoc 2 0 release Complete rewrite of the Perl scripts with attention to security issues Administration now from the cdadmin command line tool Hig
34. rective ScriptAlias user cgi bin pathtouserhome user public_html cgi bin Either directive also requires the Directory directive to allow users to access that directory lt Directory pathtouserhome user public_html cgi bin gt AllowOverride None Options None Order allow deny Allow from all lt Directory gt See the Apache documentation for more help in troubleshooting and configuring Apache S 2340 21 13 Installing CrayDoc 4 Before you install CrayDoc you need to have made note of some important items e The location of your httpd conf file e The five key values from your httpd conf file see Chapter 3 page 11 e In which mode you will install CrayDoc see Chapter 2 page 7 4 1 Automated Installation S 2340 21 The easiest way to install CrayDoc is to mount the CDand run the install script Usually this will require you to be logged in as the root user since most systems allow only the root user to mount the CD Also the install script will attempt to chown the installed files and some systems allow only the root user to chown files prompt gt mount cdrommountpoint prompt gt ed cdrommountpoint prompt gt install where cdrommountpoint is the mount point of your CD drive On a Linux system this is usually mnt cdrom Caution Your CrayDoc settings are closely tied to your Apache settings so make a note of the relevant Apache settings before you run the install script see Section 3 1
35. set to more by default You can edit this to use either your PAGER setting as defined in your shell environment or some other paging tool on your system like less by changing the pager variable in the interactive pm Perl module See Section 6 4 page 28 for the location of the interactive pm module Consult your local man page for more on more The cdadmin tool was designed to guide you through the process of installing and removing both packages of documents and individual documents You can S 2340 21 Administration 6 also reindex the search engine which you should do each time you are finished removing or installing documents At any time you may type q or e to exit the cdadmin tool Note The cdadmin tool will allow you to install your own local documentation on the CrayDoc server so that you can make custom documents available to your users Select the Install Custom Documents mode to create a new local publication number title and brief summary You may install documents of any format you wish but only HTML files will be indexed by the search engine Any HTML files you install should be placed inside a directory named html pubnumber where pubnumber is the local publication number you created for your documents The html pubnumber directory should be a subdirectory of the directory library pubnumber The cdadmin will create these directories for you as part ofthe Install Custom Documents mode 6 3 The Search Engi
36. support a particular version of a software product S 2340 21 Administration 6 This chapter addresses the administration of your CrayDoc system including installation and removal of Cray documentation packages 6 1 Tools When you installed your CrayDoc server software you should have installed a number of administration tools as well as is as a service to the administrator with no implied support from Cray O Warning The following scripts with the exception of cdadmin are provided Use them at your own risk The following tools should have been installed autohomepage pl cdadmin cdbackup sh check index cron S 2340 21 Perl script to create custom index html pages for your book directories By default this script uses the craydoc pm Perl module installed in ScriptAlias modules to create an HTML document showing the contents of a book directory in a style consistent with the rest of the CrayDoc user interface You can modify either the autohomepage pl script the index html page that is produced or the craydoc pm module itself to change the look and feel of your book directory home page The main administration tool for the CrayDoc server system See Section 6 2 page 26 for a complete description of how to use this tool A simple Bourne shell script for making a backup of your most important databases Perl script intended to be run from a cron job check index cron will compare the tim
37. ts MN 55120 1128 USA vii Introduction 1 1 1 Compatibility S 2340 21 The CrayDoc software suite is a collection of open source software components that allow easy searching and viewing of Cray documentation from a web browser This document guides the system administrator through the installation and maintenance of CrayDoc This document assumes you have a good understanding of file system permissions and basic system administration skills This document does not attempt to cover the installation and configuration of Apache or Perl because these packages are well documented on their own Refer to the documentation that accompanies each distribution CrayDoc should run under any operating system based on UNIX or Linux and has been tested on the following systems e Linux 2 2 e Linux 2 4 e Solaris 8 e IRIX 6 5 x The look and feel of the CrayDoc Hypertext Markup Language HTML user interface was designed with Netscape in mind but it should display with any web browser including Lynx Both frames and non frames versions are included Note On many browsers other than Netscape you should remember to hold the SHIFT key to select multiple entries on scrolling lists Red Hat Linux releases 6 2 and later include all the required software as part of a standard installation We cannot emphasize enough how easy it is to use CrayDoc with a standard Red Hat Linux system CrayDoc 2 0 was developed on a Red Hat Linux 7 2 system
Download Pdf Manuals
Related Search