.!								AAAREADME.RNO
.! Variants:  	SIGTAPE	- VAX SIG Symposium tape distribution
.!		UUCP	- uucp distribution, e.g. from uunet's archives.
.!		MAGTAPE	- magtape by mail distribution (e.g. from Kent Brodie).
.!			may also be suitable for (eventual) DECUS Library
.!			submission.
.!		FTP	- FTP distribution.
.!	Variants only affect recovery and file installation instructions.
.!
.! standard beginning
.flags uppercase {
.flags lowercase }
.flags accept \
.flags underline _
.no flags bold
.!flags bold %
.flags hyphenate `
.flags break |
.flags space ^
.flags period ~
.no flags capitalize
.no flags overstrike
.!flags overstrike <
.no flags subindex
.!flags substitute $
.no flags substitute
.no autosubtitle
.no justify
.no autojustify
.sthl 4,0,6,7,7,2,1,7,2 .! run-in heads at level 4, no levels all caps
.spr 0,1,2		.! change if indented paragraphs desired
.ap
.IF SIGTAPE
.ps 55,80
.lm 5
.rm 75
.title DECUS uucp version 2.0
.subtitle Cover Letter, SIGtape Distribution
.c;The VMSnet Working Group (U.S. VAX Systems SIG) Submissions
.c;DECUS uucp, Version 2.0
.s
This directory tree contains
.ELSE SIGTAPE
.ps 60,65
.rm 65
.title DECUS uucp version 2.0
.ENDIF SIGTAPE
.IF MAGTAPE
.subtitle Cover Letter, Magtape Distribution
.first title
The savesets on this tape contain
.ENDIF MAGTAPE
.IF FTP
.subtitle Cover Letter, FTP Distribution
.first title
The compressed savesets in this directory contain
.ENDIF FTP
.IF UUCP
.subtitle Cover Letter, uucp Distribution
.first title
The compressed savesets in this directory contain
.ENDIF UUCP
Version 2.0 of DECUS uucp
(formerly "VMSnet software"),
a package which allows VMS systems to exchange mail, files, and
network news with other
systems (including Unix systems, and VMS systems running this software)
using the uucp "g" protocol.
Geoff Huston's ANU News, Version 6.1 Alpha-4 is included,
along with command procedures and programs for transferring news via uucp.
 
Everything here has been compiled and linked under VMS^V5.4-x or 5.5.
All images are known to work under 5.4-x, and possibly earlier versions.
Object files are present (in the "development" savesets) for aid in linking
under earlier versions.
 
.IF SIGTAPE
For distribution via the VAX SIG Symposium tape,
almost all of the files have been placed in compressed BACKUP savesets.
(The exceptions are: the documentation; and the programs and files
needed to decompress and restore the compressed savesets.)~
Full documentation is in [UUCP.DOC]USRGD20.MEM, and in other files
described therein.
.ENDIF SIGTAPE
.IF FTP
For distribution via FTP,
the package has been divided into several savesets.
All but one of these savesets (UU20BOOT.BKP) has been compressed
(indicated by the -Z suffix in their file names).
UU20BOOT.BKP contains the main documentation for the package
([UUCP.DOC]USRGD20.MEM),
directory listings of the savesets and of the entire [UUCP] tree,
and tools for decompressing the other savesets
(which are also used elsewhere within uucp).
.ENDIF FTP
.IF MAGTAPE
For distribution via magtape,
the package has been divided into several savesets.
The first saveset on the tape,
UU20BOOT.BKP, contains the main documentation for the package
([UUCP.DOC]USRGD20.MEM),
directory listings of the savesets and of the entire [UUCP] tree,
and the COMPRESS and MODATT programs
(not needed for restoring the magtape distribution,
but included because they're needed elsewhere in uucp and in news).
.ENDIF MAGTAPE
.IF UUCP
For distribution via uucp,
the package has been divided into several savesets, all of which have been
compressed (indicated by the -Z suffix in their file names),
plus PREBOOT.VMS\_SHARE, a self-unpacking command procedure.
The latter contains the files and programs necessary to decompress
and restore the "bootstrap" saveset, UU20BOOT.BKP-Z.
Saveset UU20BOOT.BKP in turn contains the main documentation for the package
([UUCP.DOC]USRGD20.MEM),
directory listings of the other savesets and of the entire [UUCP] tree,
and files necessary for decompressing the other savesets.
Instructions for fetching and restoring the "bootstrap" saveset
appear at the end of this file.
.ENDIF UUCP
 
Chapter 2, "Installing the Files", of USRGD20.MEM contains descriptions of
the contents of each saveset (so you can decide which ones you need)
plus instructions for restoring them.
 
.IF MAGTAPE
The
.ELSE MAGTAPE
After decompression, the
.ENDIF MAGTAPE
total space required for the [UUCP...] tree is about 57,000 blocks.
However, at least half of this (source and object files)
will not be needed by most sites;
sites that don't need the uucp maps and aren't running news
can run uucp in about 6,000 blocks (plus log files).
Sites that are currently running older versions of DECUS uucp and/or NEWS
will probably need only the RUN.BKP saveset and
.IF SIGTAPE
the "loose" files in this tree.
.ELSE SIGTAPE
the UU20BOOT.BKP saveset.
.ENDIF SIGTAPE
After restoring them as described
.IF UUCP
here and
.ENDIF UUCP
in "Installing the Files",
see the appendix, "Upgrading from Previous Versions", in USRGD20.MEM.
.s
.c;principal contributors:
.s
.c;Jamie Hanrahan, Kernel Mode Consulting
.c;POB 16540, San Diego, CA 92176
.c;+1 619 284 8492^^^^jeh@cmkrnl.com
.s
.no fill
.justify
Tom^Allebrandi^II Mark^Pizzolato
Inland^Steel^Research^Labs 1558^Fernside^Street
East^Chicago,^IN Redwood^City^CA^94061
+1^219^399^6306 +1^415^369^9366
allebrandi@inland.com mark@infocomm.com
....!decwrl!simpact!inland!allebrandi ...!decwrl!infopiz!mark
.fill
.no justify
.page
.subtitle Release Notes
 
.hl 1 Restoring the Files -- [UUCP] Must Be a UFD
 
The [UUCP] directory must be a UFD;
that is, its parent directory must be [000000].
Placing UUCP.DIR under another directory on the disk will not work,
even with a rooted logical.
 
.hl 1 Restoring the UU20BOOT.BKP Saveset (network distributions)
 
The documentation states that the target of the BACKUP command to
restore this saveset should be [UUCP...].
This is incorrect and will result in an extra layer of directories.
Use a target of [*...] instead.
 
.hl 1 Restoring Compressed Savesets (Network distributions)
 
The documentation states that, after fetching the compressed savesets
from the ftp host, they can be placed anywhere in the [UUCP...] tree.
There is a bug in DECOMP\_DIST\_20.COM that requires them to be placed
in the [UUCP] directory.
 
.hl 1 Restoring the Files with an Existing [UUCP] Tree
 
If you are already running a previous version of DECUS uucp,
note that the restoration procedures described
.IF UUCP
here
.ELSE UUCP
in "Installing the Files" in the document
.ENDIF UUCP
is intended to place the files from this distribution into your existing
[UUCP...]
directory tree, with the new files superseding the old
(by use of the /NEW\_VERSION qualifier on the BACKUP command).
This is intentional!
Do not attempt to defeat this mechanism
(for example, do not try to place the 2.0 files in a tree of their own).
The automatic upgrade mechanisms we have provided may not work properly
unless the new files coexist in the [UUCP...] tree with the old ones.
Again, read the Appendix, "Upgrading from Previous Versions",
in USRGD20.MEM for details on upgrading.
 
Your files in [UUCP.CFG] will {_not}_ be superseded.
The automatic upgrade procedures will preserve the definitions of
all standard logical names defined in your existing UUCP\_SYSTARTUP.COM and
NEWS\_SYSTARTUP.COM; these will be propagated to their new home in the
CONTROL\. file.
Other changes which you have made to these procedure will of course
{_not}_ be propagated,
but the previous file versions will not be purged,
so you will be able to migrate your changes into the new files (if you desire).
 
.hl 1 Upgrade Instructions
 
.hl 2 Appendix got "lost" in the Runoff input
 
Due to a typo in the Runoff input,
the instructions for upgrading do not appear as a separate
Appendix in the document.
They appear at the end of the Appendix, "Security Issues".
 
To correct this and produce a corrected document,
restore the [UUCP.DOC.MISC] directory (in the SUPPDOC saveset),
edit USRGD20.RNO, and find the lines that read
.s
.literal
	column 1
	v
	appendix Upgrading from Previous Versions
	.!!UPGRADE
.end literal
.s
Insert a period in front of the word "appendix", so that the line appears as
.s
.i8;.appendix Upgrading from Previous Versions
 
Exit the editor, and with your default device and directory set to
[UUCP.DOC.MISC], invoke the command procedure:
.s
.i8;$ @USRGD20
 
This will build a new version of [UUCP.DOC]USRGD20.MEM^.
You can PURGE the old version of USRGD20.RNO^.
 
.hl 2 "Stacked" commands to UUCP\_CONFIG don't work
 
The upgrade instructions in the appendix include the following command:
.s
.i8;$ @UUCP\_BIN:UUCP\_CONFIG 1 "" 4 "" 6
 
This is supposed to execute menu items "1" and "4" in sequence,
automatically answering "yes" to the prompts issued by each,
and then exit the procedure (menu item "6").
However, this automatic execution does not always work.
 
Instead, invoke @UUCP\_BIN:UUCP\_CONFIG with no command-line parameters,
and request the menu items individually.
 
.hl 1 Obsolete Files that were Accidentally Distributed
 
The file [UUCP.BIN]NEWS\_RECLAIM.COM is obsolete; its functions are performed
(better) by NEWSSKIM.COM.
Please delete this file.
 
.hl 1 New News Directory Arrangement
 
This version of the uucp/news integration code has a requirement that the
NEWS\_MANAGER directory tree reside on the same disk device as that referenced
by the NEWS\_DEVICE logical (home of the .ITM files).
Some objection has been raised to this from sites running previous versions.
 
The reasons for this requirement are described in some detail in the main
documentation, USRGD20.MEM, in the Appendix,
"Miscellaneous Questions and Answers".
A summary follows.
 
In the past, placement of NEWS\_MANAGER on a different device than the
news .ITM files might have been preferable from a performance standpoint,
since during the processing of inbound news batches, incoming news items are
placed not only in .ITM files but also in subdirectories under NEWS\_MANAGER
(for forwarding to downstream sites),
and it is desirable to spread this I/O load among multiple spindles.
However, the forwarding code has been completely rewritten so that
file open, write, and close operations on the forwarding files
have been greatly reduced.
Hence the performance of an ADD BATCH operation is limited by the time required
to create the .ITM files and to update the indexed files,
and will not be much affected by the placement of NEWS\_MANAGER.
 
Another issue is that of disk fragmentation.
The NEWS\_DEVICE, which contains tens of thousands of small .ITM files
which are created and then deleted as the items are expired,
quickly becomes very fragmented.
So it has always been desirable to place NEWS\_DEVICE
on a separate disk from NEWS\_ROOT (which contains a few large indexed files).
 
However, it turns out that if you are concerned about disk fragmentation,
the NEWS\_DEVICE disk is actually a better place for the
NEWS\_MANAGER tree than is the NEWS\_ROOT disk,
since most of the activity in NEWS\_MANAGER will be the batch forwarding files,
which are created and then soon deleted^-- much like news item files!
It is true that the forwarding files are larger than the item files,
but the key point is that they are {_sequential}_ files,
and fragmentation does not affect sequential files nearly as much as it
does indexed files.
(Given these considerations, it might be reasonable to move UUCP\_LOG and
NEWS\_LOG onto the NEWS\_DEVICE disk as well.)
 
There is no particular reason (performance or fragmentation)
to put NEWS\_MANAGER on a third disk
(separate from NEWS\_ROOT and NEWS\_DEVICE) either.
I/O to the NEWS\_MANAGER tree is just not that large a load under the current
code.
 
Moving NEWS\_MANAGER onto the NEWS\_DEVICE disk
is due to assumptions that are made in NEWS\_RNEWS and NEWSSKIM,
assumptions that are being made to avoid potential deadlocks of news flow,
due to disk space considerations.
These potential deadlocks can be avoided if you have NEWS\_DEVICE
and NEWS\_MANAGER
on a different disk than UUCP\_DISK.
If NEWS\_DEVICE is the same device as UUCP\_DISK,
the potential will always exist.
 
NEWS\_MANAGER will occupy a peak of approximately 2*(1+n) amount of
extra disk space (for the uncompressed copy of the original batch, and copies
for each down stream site), but only for one hour (at most)
after the arrival of the batch.
Space on the NEWS\_DEVICE (home of the item files)
already has the largest dynamic range since even
without feeding any downstream sites, stuff comes in all day, and space
usage peaks just prior to the nightly skim.  With a reasonably full feed,
this variation is more than 50mb on a typical day with peaks FAR greater
than that depending on how smooth things are flowing in the net in general
(I've gotten peaks of 50MB compressed in from DECWRL in a single day).
 
Feeding multiple sites implies that a single inbound batch can explode by a
significant number while it is being processed.  In order to handle the
dynamics of this explosion it should be stored on the device that already
has the need/capacity for large usage fluctuations.
 
It may be argued that due to the "explosion" of an inbound batch into
multiple outbound batches,
a separate device should be used for NEWS\_MANAGER.
However, due to the (now) hourly run of NEWSSKIM,
the outbound batches stay in the NEWS\_MANAGER directory for no more than
an hour (assuming that space is available for them in the UUCP\_SPOOL
directory),
while the news items in the local news database are typically held for
at least one full day, typically several days to a few weeks,
and possibly much longer.
Hence the contribution of the outbound batches in NEWS\_MANAGER to the
total space used on the NEWS\_MANAGER/NEWS\_DEVICE volume is very small
compared to the news items files.
The flow control mechanisms built into NEWSSKIM and NEWS\_RNEWS ensure
that no deadlocks can occur due to space problems,
but these mechanisms will only work if the files are distributed
among volumes in the supported way.
 
 
.IF UUCP
.page
.subtitle Fetching and Restoring from a UUCP Host (e.g\. UUNET)
 
.c;Fetching and Restoring from a UUCP Host (e.g\. UUNET)
 
Following are special instructions for fetching the DECUS uucp 2.0 savesets
from a uucp host such as uunet, and for restoring them to a VMS disk.
 
We assume that you either have an earlier version of DECUS uucp running,
or that you have a Unix machine with uucp, in order to fetch the files.
 
In order to save both disk space on the uucp host and transmission time,
{_all}_ of the savesets here have been compressed (indicated by the -Z
suffix in their file names).
Since we don't know if you have the necessary tools to decompress the
savesets and fix up their file attributes,
we have provided them here in a VMS\_SHARE file, PREBOOT.VMS\_SHARE.
 
.lm+1
.ls1
.le;Create a [UUCP] directory and a [UUCP.BIN] subdirectory (if
you don't have them already).
 
.note
The [UUCP] directory must be a UFD;
that is, its parent directory must be [000000].
Placing UUCP.DIR under another directory on the disk will not work,
even with a rooted logical.
.end note
 
.le;Fetch these files from the uucp host and place them into the
the indicated directories:
.s
.ls0,"o"
.le;PREBOOT.VMS\_SHARE^-- place in [UUCP.BIN]
.le;UU20BOOT.BKP-Z^-- place in [UUCP]
.els0
 
Do {_not}_ fetch the RUN.BKP-Z file,
or any other savessets besides UU20BOOT, at this time.
 
.le;Set your default device and directory to [UUCP.BIN], and
invoke PREBOOT.VMS\_SHARE as a command procedure, e.g.
.s
.i8;$ SET DEFAULT ddcu:[UUCP.BIN]
.i8;$ @PREBOOT.VMS\_SHARE
 
this will "unpack" into the following files:
.s
.ls0,"-"
.le;UU20BOOT.ATT - RMS attributes for UU20BOOT.BKP
.le;COMPRESS.EXE - compresses and decompresses files
.le;MODATT.EXE - executable image for modifying file attributes
.le;MODATT.CLD - command definition file for MODATT.EXE
.le;DECOMP\_DIST\_20.COM - command procedure to decompress,
fix RMS attributes, and restore compressed backup savesets
.els0
 
.le;Rename the UU20BOOT.ATT file into the [UUCP] directory:
.s
.i8;$ RENAME UU20BOOT.ATT [-]
 
.le;Finally, invoke DECOMP\_DIST\_20.COM as a command procedure:
.s
.i8;$ @[.BIN]DECOMP\_DIST\_20
 
This will report "decompressing UU20BOOT.BKP" followed by
"restoring UU20BOOT.BKP".  The latter step will cause the creation of
several files in the [UUCP] tree.
A few of these will be duplicates of files that came in the preboot;
don't worry about this.
Ignore any %DELETE-W-SEARCHFAIL ... file not found messages.
 
.le;Do not delete any of the *.ATT files in [UUCP] !!!
 
.le;In [UUCP.DOC] you will find USRGD20.MEM, which is the
main documentation for the DECUS uucp package.
Print it on any plain-ascii printer.
Chapter 2, titled "Installing the Files",
describes the contents of the other savesets.
Read this chapter to determine which savesets you want.
(Note, the "MAP.BKP" saveset mentioned there is not present on uunet;
see below.)~
If you are already running an earlier version of DECUS uucp,
read the Appendix, "Upgrading from Previous Versions", as well.
 
.le;Fetch whichever other savesets you desire from the uucp host, placing
them in [UUCP].
 
.le;Invoke DECOMP\_DIST\_20.COM again to decompress and restore the
additional savesets.
.els0
.lm-1
.s
.c;Obtaining UUCP Maps from UUNET
 
The MAP.BKP saveset described in USRGD20.MEM
is not provided in the directory on uunet,
because uunet keeps the latest maps available elsewhere,
in a compressed "tar" (Unix tape archive) file.
The DECUS uucp kit includes a "TARREAD" utility for reading such files.
Following are instructions for obtaining them.
(We assume that you have already fetched and restored
PREBOOT.VMS\_SHARE, UU20BOOT.BKP, and RUN.BKP.)
.lm+1
.ls1
.le;Fetch the file "uunet!~/uumap.tar.Z", with a VMS name of UUMAP.TAR-Z^.
Wait for the file to arrive.
 
.le;If the UUCP\_BIN logical name is not already defined,
define it to point to the [UUCP.BIN] directory.
 
.le;If the "compress" symbol is not already defined, use
.s
.i8;$ @UUCP\_BIN:USERCMDS
 
to define it.
 
.le;SET DEFAULT to the directory containing the file UUMAP.TAR-Z^.
 
.le;Decompress the file:
.s
.i8;$ COMPRESS -D UUMAP.TAR
 
.le;Define the logical name "TAPE" to point to the decompressed file:
.s
.i8;$ DEFINE TAPE ddcu:[dire]UUMAP.TAR
 
.le;SET DEFAULT to the directory to which the maps will be restored:
.s
.I8;$ SET DEFAULT [UUCP.DATA.MAPSRC]
 
.le;Define a foreign command for the "tar read" utility, and invoke it
to unpack the tar file:
.s
.I8;$ TARREAD == "$UUCP\_BIN:TARREAD"
.I8;$ TARREAD XV
 
.le;Invoke the "FIXTARMAP" command procedure to fix up the file names of
the map files:
.s
.I8;$ @UUCP\_BIN:FIXTARMAP
 
.le;Finally, delete the tar file:
.s
.i8;$ DELETE ddcu:[dire]UUMAP.TAR;
 
.els0
.lm-1
 
.ENDIF UUCP
.! end