(userguide\NEWSRDR User's Guide) (NEWSRDR_INST_1) (NEWSRDR Installation Guide) <ABSTRACT>(August, 1994) <P>This manual describes the installation of NEWSRDR, an NNTP-based news reader for VMS systems. <ENDABSTRACT> <REVISION_INFO>(This is a revised manual.) <REVISION_INFO>(Operating System and Version:\VAX/VMS V5.0 or later; OpenVMS AXP V1.0 or later) <REVISION_INFO>(Software Version:\NEWSRDR V4.8) <ENDTITLE_PAGE>(Matthew Madison<LINE>MadGoat Software) <COPYRIGHT_PAGE> <PRINT_DATE>(11 August 1994) <p>Permission is granted to copy and redistribute this document for no commercial gain. <P>The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. <p><emphasis>(DISCLAIMER:\bold) The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. <P>The following are trademarks of Digital Equipment Corporation: <TABLE> <TABLE_ATTRIBUTES>(SINGLE_SPACED) <TABLE_SETUP>(3\20\20) <TABLE_ROW>(AXP\DEC\OpenVMS) <TABLE_ROW>(VAX\VMS\) <ENDTABLE> <p>MultiNet is a registered trademark of TGV, Inc. <COPYRIGHT_DATE>(1993, 1994\MadGoat Software. All Rights Reserved.) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(\NEWSRDR_INST_2) <p>The NEWSRDR utility provides an interface to USENET news that may be more familiar to VMS users. NEWSRDR attempts to follow the conventions of the VMS MAIL utility in its presentation and command structure whenever possible. <head1>(Intended Audience\NEWSRDR_INST_3) <p>This manual is intended for system managers responsible for installing and setting up NEWSRDR. <head1>(Document Structure\NEWSRDR_INST_4) <p>This document consists of two chapters. Chapter 1 describes the installation of NETLIB, the network interface library used by NEWSRDR. Chapter 2 describes the installation and configuration of NEWSRDR. <head1>(Related Documents\NEWSRDR_INST_5) <p>The <reference>(userguide) describes how to use NEWSRDR and all NEWSRDR commands. <p>Internet RFC 1036, <emphasis>(Standard for Interchange of USENET Messages) explains the structure of USENET news articles. RFC 977, <emphasis>(Network News Transfer Protocol), describes NNTP news service. The Internet RFC's are available via anonymous FTP from NIC.DDN.MIL. <head1>(MadGoat Software Mailing Lists\mgswls) <P>MadGoat Software has set up the following mailing lists for discussions and support of its products: <LIST>(UNNUMBERED) <LE><EMPHASIS>(Info-MadGoat@wkuvx1.wku.edu) <P> Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to <EMPHASIS>(Info-MadGoat-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <LE><EMPHASIS>(MadGoat-Announce@wkuvx1.wku.edu) <P> Announcements of new releases and new products from MadGoat. To subscribe, send a message to <EMPHASIS>(MadGoat-Announce-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <LE><EMPHASIS>(MadGoat-Bugs@wkuvx1.wku.edu) <P> Address for reporting bugs in MadGoat Software products. Please include the name of the package and version in the subject header of the message, so the report can be more easily directed to the appropriate developer. <ENDLIST> <PREFACE_SECTION>(OpenVMS AXP V1.5 Compatibility Note\v15_bug) <p> A bug in the DEC C Run-Time Library under OpenVMS AXP V1.5 will cause NEWSRDR to exit with an access violation (ACCVIO) when it tries to signal an error. A fix for this bug is available from Digital customer support. The identification of this patch is CSC Patch #378 (CSCPAT_0378); DSNlink users can obtain this patch electronically using DSNLINK VTX. <ENDPREFACE> <ENDFRONT_MATTER> <CHAPTER>(Installing NETLIB\NEWSRDR_INST_6) <note> NEWSRDR can use either a Berkeley socket library or the provided NETLIB library for communicating with the NNTP server over TCP/IP. If your TCP/IP package supports a Berkeley socket interface, you do not need to install NETLIB for use with NEWSRDR, and should skip this chapter. <endnote> <p>NEWSRDR can use the NETLIB library for communicating on a TCP/IP network. NETLIB is a layered library that is used by several of the network utilities available from MadGoat Software. It provides basic TCP and UDP services layered on top of one of several vendors' TCP/IP packages. As of this writing, NETLIB supports CMU-Tek TCP/IP, DEC TCP/IP Services for VMS, Process Software's TCPware, TGV MultiNet, and The Wollongong Group's WIN/TCP and PathWay products. <head1>(Determining Whether NETLIB is Installed\NEWSRDR_INST_7) <p>You only need to install the NETLIB libraries if they have not already been installed on your system. You can check for NETLIB's existence with the commands <interactive> <s>($ )<u>(SHOW LOGICAL NETLIB_DIR) <s>($ )<u>(SHOW LOGICAL NETLIB_SHRXFR) <s>($ )<u>(SHOW LOGICAL NETLIB_SHR) <endinteractive> <p>If these commands succeed, and the files that they point to exist, then NETLIB is installed and you can skip to the next chapter. <head1>(Installing NETLIB System-wide\NEWSRDR_INST_8) <p>NETLIB is provided in a distribution kit suitable for installation with VMSINSTAL. The release notes in the A save set of the distribution kit describe installation requirements for NETLIB. You can retrieve the release notes by using OPTIONS N on VMSINSTAL: <interactive> <s>($ )<u>(@SYS$UPDATE:VMSINSTAL NETLIB disk:[directory] OPTIONS N) <endinteractive> <p>Once NETLIB has been installed, it should be started by invoking its startup command procedure: <interactive> <s>($ )<u>(@SYS$STARTUP:NETLIB_STARTUP) <endinteractive> <p>This should be done from a suitably privileged account, before you try to install NEWSRDR. <head1>(Personal NETLIB Installation\NEWSRDR_INST_9) <P>If you are not a system manager but still want to use NEWSRDR, you can install a copy of NETLIB for your own personal use. To do this, create a temporary working directory and SET DEFAULT to it: <interactive> <s>($ )<u>(CREATE/DIRECTORY [.TEMP]) <s>($ )<u>(SET DEFAULT [.TEMP]) <endinteractive> <p>Next, unload the contents of the NETLIB<emphasis>(vvu).B save set into the working directory and execute NETLIB_USER_INSTALL.COM (substitute appropriate values for <emphasis>(vvu); for example, 016 for NETLIB V1.6): <interactive> <s>($ )<U>(BACKUP disk:[dir]NETLIBvvn.B/SAVE []) <S>($ )<U>(@NETLIB_USER_INSTALL) <endinteractive> <p>Answer the questions from the installation script and the NETLIB files will be created. Once the installation procedure is complete, you can delete the files and the working directory: <interactive> <s>($ )<u>(SET DEFAULT [-]) <s>($ )<u>(DELETE [.TEMP]*.*;*) <s>($ )<U>(SET PROTECTION=O:RWED TEMP.DIR) <S>($ )<U>(DELETE TEMP.DIR;) <ENDINTERACTIVE> <head2>(Personal NETLIB Restriction\NEWSRDR_INST_10) <p>You cannot use a personal NETLIB with NETLIB-based applications that are installed with privileges. <chapter>(Installing NEWSRDR\NEWSRDR_INST_11) <p>NEWSRDR consists of a main executable image (with some possible additions, as described later in this chapter) and requires the following logical names for configuration purposes: <table>(NEWSRDR system logical names\lognamtable) <table_attributes>(WIDE) <table_setup>(2\25) <table_heads>(Logical Name\Meaning) <table_row>(NEWSRDR_ANNOUNCE\a message (or a pointer to a file containing a message) that is displayed whe NEWSRDR starts up.) <table_row>(NEWSRDR_BANG_ADDRESS\controls whether NEWSRDR generates UUCP bang-format addresses for From and Reply-To headers (as opposed to user@host format). Default is FALSE.) <table_row>(NEWSRDR_BANG_PATH\controls whether NEWSRDR generates UUCP bang-format addresses for the Path header (as opposed to user@host format). Default is TRUE. Ignored if NEWSRDR_DO_PATH is FALSE.) <table_row>(NEWSRDR_DISABLE_USER_REPLY_TO\when TRUE, users cannot set their own Reply-To headers. Default is FALSE.) <table_row>(NEWSRDR_DISALLOW_POSTING\when defined, the user is prevented from posting any articles.) <table_row>(NEWSRDR_DO_DATE\controls whether NEWSRDR generates its own Date headers. Default is FALSE.) <table_row>(NEWSRDR_DO_MESSAGE-ID\controls whether NEWSRDR generates its own Message-ID headers. Default is FALSE.) <table_row>(NEWSRDR_DO_NEWGROUPS\controls whether NEWSRDR sends a NEWGROUPS command to the server at startup. Default is TRUE. Should only be set to FALSE if your NNTP server aborts when it receives a NEWGROUPS command.) <table_row>(NEWSRDR_DO_PATH\controls whether NEWSRDR includes a Path: header in articles it posts. Default is TRUE. Should be set to FALSE if requested by the manager of your NNTP server.) <table_row>(NEWSRDR_FAKE_NEWGROUPS\when TRUE, NEWSRDR does its own new newsgroup discovery. Default is FALSE. Can be set to TRUE if your server does not support NEWGROUPS and you want automatic newsgroup discovery. Use of this feature causes all NEWSRDR profiles to list all newgroups on the news server, which consumes much more disk space per user than when this option is disabled.) <table_row>(NEWSRDR_INITIAL_GROUPS\a list of newsgroups that new users will get subscribed to automatically the first time they use NEWSRDR.) <table_row>(NEWSRDR_MAIL_NODE\the node name of the system for mail purposes. This is used in constructing return addresses in mail messages and news articles.) <table_row>(NEWSRDR_MAIL_PROTOCOL\the VMS MAIL foreign protocol prefix to be attached to outgoing mail addresses. The prefix should include the trailing percent-sign (e.g., "MX%", "INET%")). <table_row>(NEWSRDR_NO_XHDR\disables the attempted use of the XHDR extended NNTP command.) <table_row>(NEWSRDR_NO_XOVER\disables the attempted use of the XOVER extended NNTP command.) <table_row>(NEWSRDR_NODE_NAME\the node name of the system for news purposes. This is generally the same as the Internet node name or the mail node name.) <table_row>(NEWSRDR_ORGANIZATION\The name of the organization to be used in the <quote>(Organization:) header in news articles. Optional.) <table_row>(NEWSRDR_SERVER\The Internet node name of the NNTP news server to be used for NEWS sessions.) <table_row>(NEWSRDR_GMT_OFFSET\A VMS delta time string specifying the time differential between local time and Universal Coordinated Time.) <table_row>(NEWSRDR_US_DST_ZONE\Either TRUE or FALSE, depending on whether your locality observes U.S. standard daylight savings time.) <endtable> <p>The file NEWSRDR_STARTUP.COM, supplied with the distribution kit, contains sample commands needed for defining these logical names and performing the other tasks needed to make NEWSRDR available on the system. You should edit that file as needed for your system and include it in your system startup sequence. <head1>(Creating the NEWSRDR Image\linking) <p>The NEWSRDR package comes with the object code required to create the NEWSRDR image. A command procedure called LINK.COM is provided for creating the image: <interactive> <s>($ )<u>(@LINK) <endinteractive> <p>If you wish to link NEWSRDR with your TCP/IP's Berkeley socket library (if it supports one), you may need to recompile SERVER_SOCKET.C as appropriate for your TCP/IP package, and you may also need to edit LINK.COM to link against the necessary library or libraries. <head1>(Compiling NEWSRDR from Sources\compiling) <P> If you would rather build NEWSRDR from the source code, and have a C compiler (either VAX C or DEC C) installed on your system, Use the COMPILE.COM command procedure included in the NEWSRDR package: <interactive> <s>($ )<u>(@COMPILE) <endinteractive> <p> Then follow the compilation with the link step described in <reference>(linking). <head1>(Help Library\NEWSRDR_INST_13) <p>The help library for NEWSRDR may be placed in SYS$HELP, or, if you define logical name NEWSRDR_HELP to be the full file specification of the library, anywhere else on the system. For example: <interactive> <s>($ )<u>(DEFINE/SYSTEM NEWSRDR_HELP LOCAL_STUFF:[NEWSRDR]NEWSRDR_HELP.HLB) <endinteractive> <head1>(On-Line Documentation\online_doc) <P> The NEWSRDR documentation set is provided in a form suitable for use with the VMS DECwindows Bookreader program (VMS V5.3 and later). To make the NEWSRDR on-line documentation available automatically through Bookreader, place the DECW$BOOK and DECW$BOOKSHELF files provided in the distribution kit in a directory, set their protection to WORLD:RE, and set the value of the NEWSRDR_DOC_DIR symbol at the top of NEWSRDR_STARTUP.COM to be the device and directory specification for the location of the files. NEWSRDR_STARTUP will automatically modify the appropriate Bookreader logical names to make the documentation available. <head1>(Privileges Required\NEWSRDR_INST_14) <p>NEWSRDR requires TCP/IP network access to the news server to operate. On systems which use the access controls available with the CMU TCP/IP package, this may require the granting of a rights identifier to the accounts that will be using NEWSRDR. <p>NEWSRDR uses callable MAIL and the MAIL foreign protocol interface to send mail messages. Therefore, NEWSRDR will need to be INSTALLed with the same privileges as VMS MAIL's executable image, MAIL.EXE (if any). NEWSRDR never uses these privileges itself, and turns off all image privileges <EMPHASIS>(except) <emphasis>(NETMBX\BOLD) at the start of execution. If you do not wish to use NEWSRDR to send mail, you do not need to install NEWSRDR with privileges. <head2>(EXQUOTA and User Profiles\exquota) <P>If you install NEWSRDR with the EXQUOTA privilege, it will turn on that privilege when writing out a user's NEWSRDR profile (and NEWSRC file, if one is set). This is the <emphasis>(only) privilege that NEWSRDR will use if it is available, and is only used for this purpose. The privilege is not required, but makes using NEWSRDR easier for users who are close to their diskquota. <head1>(Other User Requirements\NEWSRDR_INST_15) <p>NEWSRDR has no extensive disk quota or memory requirements for most operations. The NEWSRDR_PROFILE.NRPF file created for each user contains information about only those groups to which users subscribe, and should not require more than a few disk blocks for each user. <p>When NEWSRDR retrieves news articles from a news server, it copies them into temporary files created in the user's SYS$SCRATCH directory. Extracts for reply postings, mailings, and print jobs are also created in SYS$SCRATCH. Since news articles generally do not exceed a few hundred lines, this should not be a problem for most users. <head1>(Full-Screen Output\NEWSRDR_INST_16) <p>NEWSRDR displays news articles on a page-by-page basis, much like VMS MAIL. The Screen Management Facility (SMG$) is used to obtain the terminal size and perform the screen clears for each page of output. <head1>(Callable Editors\NEWSRDR_INST_17) <p>NEWSRDR can use any callable editor for message composition that meets the following calling standard: <list>(unnumbered) <le>The callable editor's shareable library name must be xxxSHR.EXE, where <quote>(xxx) is the name by which the editor will be called. The library must reside in SYS$SHARE or must have an exec-mode logical pointing to the library elsewhere. <le>The shareable library must contain an entry point which called xxx$EDIT, which must take the input file-spec and output file-spec, both character strings passed by descriptor, as the first two arguments. If there are optional arguments, the xxx$EDIT routine must not rely on having more than two arguments present. <endlist> <p>The Digital-supplied editors TPU, EDT, and TECO, and the (layered product) DEC Language-Sensitive Editor (LSE) all follow this calling standard. Editors that do not qualify as callable can be set up as spawned editors (where the editor is spawned in a subprocess). See the description of the SET EDIT command in the <reference>(userguide) for further information. <head1>(VMS MAIL Interface\NEWSRDR_INST_18) <p>NEWSRDR uses the callable MAIL interface to send mail messages. NEWSRDR also assumes that since there is TCP/IP available on the system, there is some form of Internet mailer also available that will handle Internet-format (user@domain) addresses. <p>A further assumption is that the Internet mailer package used at your site includes a VMS MAIL <quote>(foreign mail protocol) interface library. The logical name NEWSRDR_MAIL_PROTOCOL should specify the protocol prefix used on your system, including the terminating percent-sign. This prefix is automatically prepended to any address specified when a user mails a message using NEWSRDR. <head1>(Character Conversion Support\NEWSRDR_INST_19) <p>If your news network uses a character representation for its articles that requires conversion from the DEC character set, as do Japanese sites (due to differing Kanji representations), you can accommodate the network character representation by installing a shareable library on the system containing routines that perform the character code conversions. <p>An example of a module containing such routines is provided in the file KANJI_CONVERSION.C as part of the distribution kit. To install the KANJI_CONVERSION library as your character code conversion library, you must: <list>(numbered) <le>Compile the C module (object code is provided for those without C compilers): <interactive> <s>($ )<u>(CC KANJI_CONVERSION) <endinteractive> <le>Create the shareable library image: <interactive> <s>($ )<u>(LINK/SHARE/NOTRACE KANJI_CONVERSION,SYS$INPUT:/OPT) <S>( )<U>(UNIVERSAL=NETWORK_TO_LOCAL,LOCAL_TO_NETWORK) <S>( )<U>(<key>(ctrl/Z)) <endinteractive> <le>Place the image in SYS$LIBRARY, define the appropriate NEWSRDR logical name and INSTALL the image: <interactive> <s>($ )<u>(COPY KANJI_CONVERSION.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE) <s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_CHARACTER_CONVERSION -) <S>(_$ )<U>( SYS$SHARE:KANJI_CONVERSION.EXE) <S>($ )<U>(INSTALL CREATE NEWSRDR_CHARACTER_CONVERSION/OPEN/SHARE/HEADER) <ENDINTERACTIVE> <endlist> <p>Note that you must do this from a suitably privileged account, and you must have at least one global section and three global pages free on the system to INSTALL the image. The commands for installing the image are provided in the sample NEWSRDR_STARTUP.COM command procedure provided with the NEWSRDR kit. <p>You only need to INSTALL the character conversion library if NEWSRDR is installed with privileges. <head1>(Establishing Your Time Zone\NEWSRDR_INST_20) <p>This is only required if NEWSRDR_DO_DATE is defined TRUE. <p>Two logical names control the way date/time stamps are generated by NEWSRDR for articles posted by NEWSRDR users. NEWSRDR_GMT_OFFSET should be defined as a VMS delta time specification preceded by either a plus sign or a minus sign. This value represents the time differential between local time and Universal Coordinated Time (also called Greenwich Mean Time). For the U.S. Eastern time zone, you would define it as: <interactive> <s>($ )<u>(DEFINE/SYSTEM NEWSRDR_GMT_OFFSET "-0 05:00:00") <endinteractive> <p>The minus sign indicates that Eastern time is 5 hours behind GMT. <p>The logical name NEWSRDR_US_DST_ZONE should be defined as TRUE if your locality observes U.S. standard daylight savings time (DST). This will cause NEWSRDR to automatically adjust the GMT offset during daylight savings time. If you do not observe U.S. standard DST, you may need alter the GMT offset value manually at the beginning and end of your DST period. <head1>(Name Conversion Support\NEWSRDR_INST_21) <p>If your site does not use VMS usernames for addressing local users in network mail, you can install a shareable library containing a routine that NEWSRDR will call on to perform username-to-mailname conversions for addresses that it puts in article headers. <p>An example of a module containing the routines needed to support such conversions is provided in the file NAME_CONVERSION.C as part of the distribution kit. To install a name conversion library, you must: <list>(numbered) <le>Edit and compile the C module, or develop your own module in another language that provides the same interface. <le>Create the shareable library image: <interactive> <s>($ )<u>(LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT) <s>( )<u>(UNIVERSAL=INIT,CONVERT,CLEANUP) <s>( )<u>(<KEY>(ctrl/Z)) <endinteractive> <le>Place the resulting image in SYS$LIBRARY, define the appropriate NEWSRDR logical name, and INSTALL the image: <interactive> <s>($ )<u>(COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE) <s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION SYS$SHARE:library.EXE) <S>($ )<U>(INSTALL CREATE NEWSRDR_NAME_CONVERSION/OPEN/SHARE/HEADER) <ENDINTERACTIVE> <endlist> <p>The interface used by NEWSRDR is identical to that used by MadGoat's Message Exchange E-mail software. If you already have installed a name conversion library for use with Message Exchange, you need only define a logical name to use the same library with NEWSRDR: <interactive> <s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION MX_SITE_NAME_CONVERSION) <endinteractive> <p>Refer to the sample code provided for further information on the name conversion interface. <head1>(Address Conversion Support\NEWSRDR_INST_22) <p>When NEWSRDR sends mail, it uses callable Mail routines, forming the addresses by translating the logical name NEWSRDR_MAIL_PROTOCOL and prefixing that to the quoted RFC822 destination address. If your site requires a more sophisticated translation (such as domain name reversal or better handling of special characters in addresses), you can install your own address conversion routine to perform this function. <p>An example of a module containing the routines needed to support such conversions is provided in the file ADDRESS_CONVERSION.C as part of the distribution kit. To install an address conversion library, you must: <list>(numbered) <le>Edit and compile the C module, or develop your own module in another language that provides the same interface. <le>Create the shareable library image: <interactive> <s>($ )<u>(LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT) <s>( )<u>(UNIVERSAL=INIT,CONVERT,CLEANUP) <s>( )<u>(<KEY>(ctrl/Z)) <endinteractive> <le>Place the resulting image in SYS$LIBRARY, define the appropriate NEWSRDR logical name, and INSTALL the image: <interactive> <s>($ )<u>(COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE) <s>($ )<u>(DEFINE/SYSTEM/EXEC NEWSRDR_ADDRESS_CONVERSION SYS$SHARE:library.EXE) <S>($ )<U>(INSTALL CREATE NEWSRDR_ADDRESS_CONVERSION/OPEN/SHARE/HEADER) <ENDINTERACTIVE> <endlist> <p>Refer to the sample code provided for further information on the address conversion interface. <head1>(Installing NEWSRDR for Personal Use\NEWSRDR_INST_23) <p>If you are not the system manager, you can install NEWSRDR for your own use, with the restriction that you may not be able to send mail using NEWSRDR (depending on your site's E-mail software). <P>To install NEWSRDR for your own use, create the NEWSRDR image as described above, place the image and the help library in directories you own, and edit NEWSRDR_STARTUP.COM to reflect the location of those files. You should also edit NEWSRDR_STARTUP.COM to remove the /SYSTEM qualifier from the definition of NEWSRDR_DEF.