Sep  1 15:02 1995                                           Page 1












			    Installing Generic NQS
				Version 3.4x.x


			 Academic Computing Services
			   University of Sheffield


				Stuart Herbert
			 (S.Herbert@sheffield.ac.uk)
Sep  1 15:02 1995                                           Page 2


Abstract :

	Under grant NTI/48.2 from the New Technologies Sub Committee (NTSC)
	of JISC, the University of Sheffield is maintaining a freely-available
	version of the Network Queueing System (NQS), the de facto standard
	batch processing system for the UNIX operating system.

	This document explains how to install, and configure, Generic NQS
	v3.40 or later.


Sep  1 15:02 1995                                           Page 3


----------------------------
	Contents
----------------------------

1	Introduction

1.1	Welcome To Generic NQS
1.2	About This Document
1.2.1		Quick Start
1.2.2		Purpose
1.2.3		Using This Document
1.2.4		Conventions
1.2.5		Contacting The Author

2	Compiling And Installing Generic NQS

2.1	Introduction
2.2	Getting Started
2.3	Edit The Makefile
2.3.1		Where NQS Is Installed
2.3.2		Which Optional Features Do You Want?
2.3.3		Which Version of UNIX You Are Using
2.3.4		File Ownership
2.3.5		Save Your Changes
2.4	Compiling The Software
2.5	Installing
2.5.1		Creating The GNQS Working Files
2.5.2		Installing The GNQS Software
2.5.3		Installing The GNQS Manual Pages
2.5.4		Adding The Service Entry
2.5.5		Creating A Machine ID
2.5.6		Start Up GNQS
2.5.7		Installation Complete

3	Upgrading From An Older Version

3.1	Introduction
3.2	Getting Started
3.3	A Non-Staged Upgrade
3.3.1		Introduction
3.3.2		Step One : Compile The Software
3.3.3		Step Two : Take A Copy Of Your Current NQS Configuration
3.3.4		Step Three : Stop NQS
3.3.5		Step Four : Install The New Version Of Generic NQS
3.3.6		Step Five : Move The NQS Spool Area
3.3.7		Step Six : Restart NQS
3.4	A Staged Upgrade
3.4.1		Introduction
3.4.2		Step One : Compile The Software
3.4.3		Step Two: Stage In The Software

4	Configuring Generic NQS

4.1	Introduction
4.2	Compute Servers
4.2.1		Introduction
Sep  1 15:02 1995                                           Page 4


----------------------------
1	Introduction
----------------------------

	--------------------
1.1	Welcome To Generic NQS

	Thank you for your interest in Generic NQS.

	Generic NQS is the continuing development of Monsanto-NQS, itself
	descended directly from the original COSMIC NQS, written under
	contract to NASA by Sterling Software, Inc.

	Since October, 1994, Monsanto-NQS (and then Generic NQS) has been
	maintained by The University of Sheffield.  We are funded to produce
	a freely-available, robust, and well-documented version of NQS for
	UK Academia.

	For more information, please see the `README' file included with the
	source code distribution, or alternatively, from :

	> http://www.shef.ac.uk/uni/projects/nqs/Product/GNQS/v3.4x/README/

	--------------------
1.2	About This Document

	----------
1.2.1	Quick Start

	One of the most frequent complaints I get about installing Generic NQS
	is that there is too much to do.  If you want to get Generic NQS
	installed, and running, with the minimum of work, then look out for
	the Quick Start Guide, which will be included with the final release
	of Generic NQS v3.40.0.

	----------
1.2.2	Purpose

	This document is supposed to provide you with all the information you
	need in order to compile, install, and setup NQS at your site for
	daily use.

	Instructions are included (in the following order) for :

	o  New Generic NQS users - compiling, and installing.

	   These are users who are installing GNQS for the very first time,
	   or who are re-installing from scratch.

	o  Existing Monsanto-NQS/Generic NQS users - upgrading.

	   These are users who are upgrading from an older version of
	   Generic NQS, or from Monsanto-NQS.

	o  How To Configure GNQS For Batch On A Single Machine

Sep  1 15:02 1995                                           Page 5


	   Typical configuration for a single compute server.

	o  How To Configure GNQS For Batch On A Cluster Of Workstations

	   Typical configuration for a set of workstations which are
	   clustered together.

	----------
1.2.3	Using This Document

	I recommend that your print this document out (or otherwise have the
	document available) so that you can follow the instructions below and
	still read this document at the same time.

	A HTML version of this document is available from the following URL :

	> http://www.shef.ac.uk/uni/projects/nqs/Product/GNQS/v3.4x/INSTALL/

	----------
1.2.4	Conventions

	During each step of the installation process, you will see a
	paragraph (or more) of instructions, followed by sample commands
	which demonstrate what to do.  Sample commands are represented by

	>  this is a sample command

	----------
1.2.5	Contacting The Author

	IF there is anything about compiling, installing, and setting up GNQS
	which this document does NOT cover, please mail the author.

	> mailto:S.Herbert@sheffield.ac.uk

	I normally reply within one working day; however, please note that
	I am on holiday until the 25th September.

Sep  1 15:02 1995                                           Page 6


----------------------------
2	Compiling And Installing Generic NQS
----------------------------

	--------------------
2.1	Introduction

	In this chapter, we look at how to compile and install the GNQS
	source code.  These instructions were written for Generic NQS
	v3.40.0, and were last updated on Friday, 1st September 1995.

	Generic NQS v3.40.0 is available from

	> ftp://www.shef.ac.uk/uni/projects/nqs/v3.40/

	--------------------
2.2	Getting Started

	Before you start, you need the following :

	o  Which version of UNIX do you have?

	   Generic NQS has been tested on the following versions of UNIX at
	   some point in its history :

	   AIX 3.2.5, 4.1; Fujitsu; HP-UX 8,9; Irix 4,5,6; Linux; NCR;
	   OSF/1; Solaris 2; SunOS 4; ULTRIX, UNICOS 8.

	   If you are successful in getting Generic NQS to work, please email
	   me, and tell me, or use the following form on the World-Wide Web :

	   > http://www.shef.ac.uk/uni/projects/nqs/Product/GNQS/v3.4x/Success.html

	--------------------
2.3	Edit The Makefile

	Change to the `proto' directory, and edit the file `Makefile'.

	>  cd Generic-NQS-3.40.0/proto
	>  vi Makefile

	----------
2.3.1	Where NQS Is Installed

	The GNQS software itself can be installed onto a central server, and
	shared between all of the workstations which mount their software
	(typically via NFS) from that server.

	The GNQS software is installed into directories off of NQS_ROOTDIR.
	NQS_ROOTDIR can be a directory which is shared via NFS between
	several machines.  For example, if NQS_ROOTDIR was `/usr/local', then
	GNQS would be installed into `/usr/local/bin', `/usr/local/sbin',
	`/usr/local/man' etc., etc.

	If you want to install GNQS into somewhere other than `/usr/local',
	then change the value of NQS_ROOTDIR.
Sep  1 15:02 1995                                           Page 7



	> NQS_ROOTDIR = /usr/local

	The GNQS software also requires temporary file space to work.  This
	temporary space MUST be unique to each machine running GNQS, although
	it can be on an NFS partition.  By default, GNQS uses the standard
	UNIX spool area, `/usr/spool'.

	If you want GNQS to store its working files elsewhere, change the
	value of NQS_ROOTPRIV.

	> NQS_ROOTPRIV = /usr/spool

	After this, the Makefile has a set of entries (from NQS_MAN to
	NQS_NMAP) which specify where to install the various components of
	Generic NQS.  We recommend that you use the default settings.

	----------
2.3.2	Which Optional Features Do You Want?

	Generic NQS now includes a number of features which you can choose
	to add, or leave out, at compile time.  The Makefile includes a
	brief list, and you can find more details in the file
	`doc/Features', or from the URL

	> http://www.shef.ac.uk/uni/projects/nqs/Product/GNQS/v3.4x/Features/

	By default, the Makefile enables the features most GNQS installations
	will want.  If you want to change which features are available, then
	change the value of FEATURES.

	>  FEATURES = -DTAMU

	----------
2.3.3	Which Version of UNIX You Are Using

	The GNQS software can be compiled on a number of platforms.  For
	each supported platform, there is an appropriate Makefile, which
	contains all the information specific to each version of UNIX.

	Please uncomment the line which selects the Makefile for your
	UNIX machine.

	> #include Makefile.linux

	becomes

	> include Makefile.linux

	for example.

	----------
2.3.4	File Ownership

	The GNQS software (and directories it uses) will be owned (by default)
	by the user `root', and the group `bin'.  If you wish to change either
Sep  1 15:02 1995                                           Page 8


	of these, edit the values of `NQS_OWNER' and `NQS_GROUP' respectively.

	> NQS_OWNER = root
	> NQS_GROUP = bin

	----------
2.3.5	Save Your Changes

	Once you have done the above, please save your changed Makefile to
	disk ready for compiling.

	--------------------
2.4	Compiling The Software

	We are now ready to compile Generic NQS.  To do so, please change
	to the `proto' directory (if you're not already there), and type
	`make'.

	> cd Generic-NQS-3.40.0/proto
	> make

	This will compile Generic NQS v3.4x, ready for installing.  Generic
	NQS is a large program, and can take over half an hour to compile
	(especially if your machine is heavily loaded).

	While Generic NQS is compiling, you will probably see your C
	compiler producing warnings.  The Generic NQS code is very old (much
	of it dates back to 1985) and while a number of people have spent
	time removing those warnings, we have not yet managed to remove them
	all.

	If Generic NQS fails to compile, please contact the author with the
	following details :

	o  Which version of UNIX you are compiling on?

	   You can get this information normally by using `uname -a'.

	o  Where there is a choice, which C ompiler you are using?

	   You can get this information normally by using `which cc'.  If
	   you are using the Free Software Foundation's GCC, please indicate
	   which version of GCC you are using.

	o  A log of the compilation.

	   You can do this by typing `make >& logfile' (if you use csh/tcsh)
	   or `make > logfile 2>1' (is you use bash/sh/ksh).  This will
	   store information only about the file that fails to compile.

	o  Anything else you think is important.

	Please email all of the above to NQS-Support@mailbase.ac.uk.

	--------------------
2.5	Installing
Sep  1 15:02 1995                                           Page 9



	----------
2.5.1	Creating The GNQS Working Files

	Once GNQS has compiled, the next step is to build the working files
	GNQS uses.  To do this, go to the `proto' directory, and type `make
	directories'.

	>  cd Generic-NQS-3.40.0/proto
	>  make directories

	----------
2.5.2	Installing The GNQS Software

	Now you can install the Generic NQS software itself, by using the
	command `make install'.

	>  cd Generic-NQS-3.40.0/proto
	>  make install

	----------
2.5.3	Installing The GNQS Manual Pages

	PLEASE NOTE: Support for installing manual pages will be added into
	the final release of Generic NQS v3.40.0.

	The Generic NQS manual pages can be installed by using the command
	`make install.man'.

	>  cd Generic-NQS-3.40.0/proto
	>  make install.man

	You will then need to rebuild your manual page database.  For some
	versions of UNIX, this is done with the command /usr/lib/whatis; for
	others, this is done using catman.  Please refer to your vendor's
	documentation.

	----------
2.5.4	Adding The Service Entry

	You next need to edit /etc/services (or modify your NIS/NIS+ database)
	to add an entry for GNQS :

	>  nqs  607/tcp           # Network Queueing System

	----------
2.5.5	Creating A Machine ID

	Your next step is to run the nmapmgr program, provided with Generic
	NQS, to allocate a machine id to your computer.  The following
	commands will use the IP address of your computer to form a machine
	id :

	>  nmapmgr
	>  NMAPMGR: add host <hostname>
	>  NMAPMGR: add alias <hostname>.<domainname> <hostname>
Sep  1 15:02 1995                                           Page 10


	>  NMAPMGR: list
	>  NMAPMGR: exit

	Each machine running NQS requires a unique machine id.  The machine id
	is used to track NQS requests as they move between different machines
	running NQS.

	If you wish to use Generic NQS in conjunction with other versions of
	NQS, then you may have to assign machine id's explicitly - some
	versions of NQS only allow machine id's which are small in value.
	See the nmapmgr(1) manual page for information on how to manually
	assign machine id's.

	----------
2.5.6	Start Up GNQS

	To start GNQS for the very first time, use the command

	>  /usr/local/lib/nqs/nqsdaemon

	substituting `/usr/local/lib/nqs' for the value of NQS_LIBEXE in the
	Generic NQS makefile.

	You should add this command to your startup scripts to restart the
	NQS daemon whenever the machine is restarted.

	----------
2.5.7	Installation Complete

	At this point, Generic NQS is now installed on your computer.  Your
	next step is to configure Generic NQS to suit your setup.  Chapter 4,
	below, has details on how to go about this, and also includes several
	example setups which may suit your needs.

Sep  1 15:02 1995                                           Page 11


----------------------------
3	Upgrading From An Older Version
----------------------------

	--------------------
3.1	Introduction

	In this chapter, we look at how to upgrade your existing version of
	Monsanto-NQS/Generic NQS to the latest Generic NQS v3.4x.x.

	--------------------
3.2	Getting Started

	You must first ask yourself the following questions :

	o  Am I upgrading from Monsanto-NQS v3.35, Monsanto-NQS v3.36.x, or
	   Generic NQS v3.4x.x?

	o  Do I intend to install this new version of Generic NQS into
	   exactly the same directories as my current version?

	If you answered `no' to either of these, then please follow the
	instructions for a `A Non-Staged Upgrade', below.

	If you answered `yes' to both questions, then please follow the
	instructions for a `A Staged Upgrade', below.

	If you are upgrading from someone else's version of NQS (eg, CERN
	NQS), then you should consider this a new installation, and follow
	the instructions given in Chapter 2.

	--------------------
3.3	A Non-Staged Upgrade

	----------
3.3.1	Introduction

	These are instructions on how to upgrade your NQS installation to use
	the software from this latest release.  These instructions should be
	followed if any of the following are true :

	o  You are upgrading from a version of Monsanto-NQS prior to v3.35.

	o  You do not wish to install this latest release in the same place
	   as your current NQS.

	----------
3.3.2	Step One : Compile The Software

	Follow the instructions in Chapter 2, above, to compile this release
	of Generic NQS.  Stop once you reach section 2.5, ``Installing''.

	----------
3.3.3	Step Two : Take A Copy Of Your Current NQS Configuration

	If you want to keep your current NQS configuration, use the qmgr(1)
Sep  1 15:02 1995                                           Page 12


	command to create a `snap-file' :

	>  qmgr 
	>  #Mgr: snap file=<filename>
	>  #Mgr: exit

	This is a precaution, in case things go horribly wrong, and you need
	to rebuild your NQS configuration.

	----------
3.3.4	Step Three : Stop NQS

	Make sure that there are no running NQS jobs, and shutdown the
	running NQS daemon :

	>  qmgr
	>  #Mgr: shutdown
	>  #Mgr: exit

	----------
3.3.5	Step Four : Install The New Version Of Generic NQS

	Install the new version of Generic NQS by using the following
	commands :

	>  cd Generic-NQS-3.40.0/proto
	>  make install
	>  make install.man

	----------
3.3.6	Step Five : Move The NQS Spool Area

	This step only applies if :

	o  You have compiled the new version of NQS to store its working
	   files into a different directory.

	Move the NQS spool area from its current place (typically,
	/usr/spool/nqs) to its new place.

	----------
3.3.7	Step Six : Restart NQS

	Finally, start up the new NQS daemon, by using qmgr :

	>  qmgr start nqs

	Your Non-Staged Upgrade should now be complete.

	--------------------
3.4	A Staged Upgrade

	----------
3.4.1	Introduction

	These are instructions for how to upgrade your NQS installation to
Sep  1 15:02 1995                                           Page 13


	use the latest Generic NQS release.  These instructions should be
	followed if all of the following are true :

	o  You are upgrading from Monsanto-NQS v3.35 or later, or from
	   Generic NQS v3.40.0 or later.

	o  You intend to install this release of Generic NQS into the 
	   SAME directories as your current version of NQS.

	----------
3.4.2	Step One : Compile The Software

	Follow the instructions in Chapter 2, above, to compile this release
	of Generic NQS.  Stop when you get to section 2.5, ``Installing''.

	Make sure that you edit the makefiles to ensure that the new NQS
	software will be installed into the same directories as your existing
	NQS software.

	----------
3.4.3	Step Two: Stage In The Software

	To stage in the new NQS software, use the following commands :

	>  cd Generic-NQS-3.40.0/proto
	>  make stage

	Your upgrade is now complete.  Your existing NQS installation will
	automatically replace itself with the new software when it can.

Sep  1 15:02 1995                                           Page 14


----------------------------
4	Configuring Generic NQS
----------------------------

	--------------------
4.1	Introduction

	This chapter explains how to configure Generic NQS once it has been
	installed.  To do this, we will work through a collection of sample
	configurations which have been contributed by various Generic NQS
	users.  Feel free to use one of these configurations for your own
	computer.  You'll find these configurations in the
	`examples/snap-file' directory included with the Generic NQS source
	code.

	Comments, and more contributed configurations, are always welcome.

	I've broken these configurations up into two groups, which represent
	the two types of computer system NQS is typically used in.

	--------------------
4.2	Compute Servers

	----------
4.2.1	Introduction

	One of the most popular uses of NQS is to impose some kind of order
	on the users of central compute servers.  These are typically
	powerful UNIX machines (eg, SGI Challenge XL), possibly acting as
	servers for a number of clustered workstations.  They have many
	large or CPU-intensive processes running concurrently.

	NQS installations on this type of machine are typically stand-alone,
	and do not dispatch jobs out to lesser machines, such as
	workstations.  Sometimes, workstations may forward jobs to the
	compute server.



----------------------------------------------------------------------------
Stuart Herbert - (S.Herbert@sheffield.ac.uk)
