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.
New Features CrayDoc™ Installation and Administration Guide 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 • Highlighting 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.
Contents Page Preface v Ordering Documentation Conventions . . Reader Comments . . . . . . . . . . . . . . . . . . . . . . v . . . . . . . . . . . . . . . . . . . . . . . . vi . . . . . . . . . . . . . . . . . . . . . . . . vii Introduction [1] Compatibility 1 . . . . . . . . . . . . . . . . . . . . . . . . . 1 Software Requirements . . . . . . . . . . . . . . . . . . . . . . .
CrayDoc™ Installation and Administration Guide Page Apache in Shared Mode . . . Apache Tips and Troubleshooting . . . . . . . . . . . . . . . . . . . 12 . . . . . . . . . . . . . . . . . . . 13 Installing CrayDoc [4] 15 Automated Installation . . . . . . . . . . . . . . . . . . . . . . . 15 Manual Installation . . . . . . . . . . . . . . . . . . . . . . . . 16 . . . . . . . . . . . . . . . . .
Preface This publication describes CrayDoc 2.0 release and installing and administering CrayDoc and Cray documentation. Ordering Documentation 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 Form link. Telephone (inside U.S., Canada): 1–800–284–2729 (BUG CRAY), then 605–9100 Telephone (outside U.S.
CrayDoc™ Installation and Administration Guide Conventions The following conventions are used throughout this document: vi Convention Meaning command This fixed-space font denotes literal items, such as file names, pathnames, man page names, command names, and programming language elements. variable Italic typeface indicates an element that you will replace with a specific value. For instance, you may replace filename with the name datafile in your program.
Preface Reader Comments 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.
Introduction [1] 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.
CrayDoc™ Installation and Administration Guide 1.2 Software Requirements 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.
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.
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 Sendmail.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.
Introduction [1] 1.3.2 Hard Drive Space 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 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.
CrayDoc™ Installation and Administration Guide 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.
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 than the user ID of the calling Apache web server.
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.
Configuring Apache [3] 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.
CrayDoc™ Installation and Administration Guide 3.1 Apache in Stand-alone Mode 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> 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.
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.
Installing CrayDoc [4] Before you install CrayDoc, you need to have made note of some important items: • The location of your httpd.conf file • The five key values from your httpd.conf file (see Chapter 3, page 11) • In which mode you will install CrayDoc (see Chapter 2, page 7) 4.1 Automated Installation The easiest way to install CrayDoc is to mount the CD and run the install script.
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.
Installing CrayDoc [4] 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> cd cdrommountpoint prompt> ls -1FC BerkeleyDB/ LICENSE.CrayDoc PerlFect/ README apache/ configure.pl craydoc/ install manpages/ manuals/ Perl/ Perl_mods/ releases/ The CD contains: S–2340–21 BerkeleyDB Directory containing source code for the Berkeley Database. If you are using Perl 5.6.
CrayDoc™ Installation and Administration Guide install Bourne shell script for automated installation of CrayDoc. This script simply finds your Perl location and then calls configure.pl. manuals Directory containing all the Cray book files. manpages Directory containing all the Cray man page files. Perl Directory containing source code for Perl 5.6.1. This version of Perl includes all the modules required for CrayDoc. Perl_mods Directory containing the Data/Dumper.pm and Mail/Sendmail.
Installing CrayDoc [4] 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.
CrayDoc™ Installation and Administration Guide DocumentRoot The full file path from where Apache will be serving files. Example: /var/www/html ScriptAlias The full file path where your scripts reside, similar to DocumentRoot. Example: /var/www/cgi User Who should own all your CrayDoc scripts and files. Group Which group all your CrayDoc scripts and files should belong to.
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.
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.
Cray Documentation [5] Cray delivers two kinds of documentation: 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.
CrayDoc™ Installation and Administration Guide 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. 5.
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. Warning: The following scripts, with the exception of cdadmin, are provided as-is, as a service to the administrator, with no implied support from Cray. Use them at your own risk.
CrayDoc™ Installation and Administration Guide 6.2 The cdadmin tool 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.
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.
CrayDoc™ Installation and Administration Guide 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 The following contents of your $ScriptAlias directory reflect what is installed: books.dmp 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). collections.
Administration [6] craydoc.pm Functions used by all the CrayDoc CGI scripts. interactive.pm Common functions for the install script and the cdadmin tool. orderform.cgi 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. packages.dmp All the software releases for which you have installed documentation.
CrayDoc™ Installation and Administration Guide 6.6 Upgrading from version 1.0 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.
Administration [6] 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> cp /var/www/cgi-bin.10/packages.dmp /var/www/cgi-bin/ prompt> 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.
Index A administration tools, Apache source code, 2 M Manual installation craydoc-config, 18 map of file locations, 21 Mode Shared, 8 Stand-alone, 7 25 B Berkeley Database source code, 3 P Perl source code, 2 C cdadmin tool, 26 Compatibility, 1 S Security, 8 permissions, 9, 11 suEXEC, 9 Sendmail.pm module, 4 Software requirements, 2 D Dumper.
