NEWSRDR Installation Guide August, 1994 This manual describes the installation of NEWSRDR, an NNTP-based news reader for VMS systems. Revision/Update Information: This is a revised manual. Operating System and Version: VAX/VMS V5.0 or later; OpenVMS AXP V1.0 or later Software Version: NEWSRDR V4.8 Matthew Madison MadGoat Software ________________________ 11 August 1994 Permission is granted to copy and redistribute this document for no commercial gain. 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. DISCLAIMER: 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. The following are trademarks of Digital Equipment Corporation: AXP DEC OpenVMS VAX VMS MultiNet is a registered trademark of TGV, Inc. __________ Copyright ©1993, 1994 MadGoat Software. All Rights Reserved. _______________________________________________________ Contents _________________________________________________ PREFACE v _________________________________________________ OPENVMS AXP V1.5 COMPATIBILITY NOTE vii _______________________________________________________ CHAPTER 1 INSTALLING NETLIB 1-1 _________________________________________________ 1.1 DETERMINING WHETHER NETLIB IS INSTALLED 1-1 _________________________________________________ 1.2 INSTALLING NETLIB SYSTEM-WIDE 1-2 _________________________________________________ 1.3 PERSONAL NETLIB INSTALLATION 1-2 1.3.1 Personal NETLIB Restriction ___ 1-3 _______________________________________________________ CHAPTER 2 INSTALLING NEWSRDR 2-1 _________________________________________________ 2.1 CREATING THE NEWSRDR IMAGE 2-5 _________________________________________________ 2.2 COMPILING NEWSRDR FROM SOURCES 2-5 _________________________________________________ 2.3 HELP LIBRARY 2-5 _________________________________________________ 2.4 ON-LINE DOCUMENTATION 2-6 iii Contents _________________________________________________ 2.5 PRIVILEGES REQUIRED 2-6 2.5.1 EXQUOTA and User Profiles _____ 2-7 _________________________________________________ 2.6 OTHER USER REQUIREMENTS 2-7 _________________________________________________ 2.7 FULL-SCREEN OUTPUT 2-7 _________________________________________________ 2.8 CALLABLE EDITORS 2-8 _________________________________________________ 2.9 VMS MAIL INTERFACE 2-8 _________________________________________________ 2.10 CHARACTER CONVERSION SUPPORT 2-9 _________________________________________________ 2.11 ESTABLISHING YOUR TIME ZONE 2-10 _________________________________________________ 2.12 NAME CONVERSION SUPPORT 2-11 _________________________________________________ 2.13 ADDRESS CONVERSION SUPPORT 2-12 _________________________________________________ 2.14 INSTALLING NEWSRDR FOR PERSONAL USE 2-13 iv Contents _______________________________________________________ TABLES 2-1 NEWSRDR system logical names __ 2-1 v _______________________________________________________ Preface 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. __________________________________________________________________ Intended Audience This manual is intended for system managers responsible for installing and setting up NEWSRDR. __________________________________________________________________ Document Structure 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. __________________________________________________________________ Related Documents The NEWSRDR User's Guide describes how to use NEWSRDR and all NEWSRDR commands. Internet RFC 1036, Standard for Interchange of USENET Messages explains the structure of USENET news articles. RFC 977, Network News Transfer Protocol, describes NNTP news service. The Internet RFC's are available via anonymous FTP from NIC.DDN.MIL. __________________________________________________________________ MadGoat Software Mailing Lists MadGoat Software has set up the following mailing lists for discussions and support of its products: o Info-MadGoat@wkuvx1.wku.edu v Preface Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to Info-MadGoat-Request@wkuvx1.wku.edu with the word SUBSCRIBE in the first line of the body of the message. o MadGoat-Announce@wkuvx1.wku.edu Announcements of new releases and new products from MadGoat. To subscribe, send a message to MadGoat-Announce-Request@wkuvx1.wku.edu with the word SUBSCRIBE in the first line of the body of the message. o MadGoat-Bugs@wkuvx1.wku.edu 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. vi _______________________________________________________ OpenVMS AXP V1.5 Compatibility Note 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. vii _______________________________________________________ 1 Installing NETLIB 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. 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. __________________________________________________________________ 1.1 Determining Whether NETLIB is Installed 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 $ SHOW LOGICAL NETLIB_DIR $ SHOW LOGICAL NETLIB_SHRXFR $ SHOW LOGICAL NETLIB_SHR If these commands succeed, and the files that they point to exist, then NETLIB is installed and you can skip to the next chapter. 1-1 Installing NETLIB __________________________________________________________________ 1.2 Installing NETLIB System-wide 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: $ @SYS$UPDATE:VMSINSTAL NETLIB disk:[directory] OPTIONS N Once NETLIB has been installed, it should be started by invoking its startup command procedure: $ @SYS$STARTUP:NETLIB_STARTUP This should be done from a suitably privileged account, before you try to install NEWSRDR. __________________________________________________________________ 1.3 Personal NETLIB Installation 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: $ CREATE/DIRECTORY [.TEMP] $ SET DEFAULT [.TEMP] Next, unload the contents of the NETLIBvvu.B save set into the working directory and execute NETLIB_USER_ INSTALL.COM (substitute appropriate values for vvu; for example, 016 for NETLIB V1.6): $ BACKUP disk:[dir]NETLIBvvn.B/SAVE [] $ @NETLIB_USER_INSTALL 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: 1-2 Installing NETLIB $ SET DEFAULT [-] $ DELETE [.TEMP]*.*;* $ SET PROTECTION=O:RWED TEMP.DIR $ DELETE TEMP.DIR; ___________________________ 1.3.1 Personal NETLIB Restriction You cannot use a personal NETLIB with NETLIB-based applications that are installed with privileges. 1-3 _______________________________________________________ 2 Installing NEWSRDR 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_2-1__NEWSRDR_system_logical_names________________ Logical_Name____________Meaning________________________ NEWSRDR_ANNOUNCE a message (or a pointer to a file containing a message) that is displayed whe NEWSRDR starts up. 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. 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. NEWSRDR_DISABLE_USER_ when TRUE, users cannot set REPLY_TO their own Reply-To headers. Default is FALSE. 2-1 Installing NEWSRDR Table_2-1_(Cont.)__NEWSRDR_system_logical_names________ Logical_Name____________Meaning________________________ NEWSRDR_DISALLOW_ when defined, the user is POSTING prevented from posting any articles. NEWSRDR_DO_DATE controls whether NEWSRDR generates its own Date headers. Default is FALSE. NEWSRDR_DO_MESSAGE-ID controls whether NEWSRDR generates its own Message-ID headers. Default is FALSE. 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. 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. 2-2 Installing NEWSRDR Table_2-1_(Cont.)__NEWSRDR_system_logical_names________ Logical_Name____________Meaning________________________ NEWSRDR_FAKE_ when TRUE, NEWSRDR does its NEWGROUPS 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. NEWSRDR_INITIAL_ a list of newsgroups that new GROUPS users will get subscribed to automatically the first time they use NEWSRDR. 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. 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%") . NEWSRDR_NO_XHDR disables the attempted use of the XHDR extended NNTP command. NEWSRDR_NO_XOVER disables the attempted use of the XOVER extended NNTP command. 2-3 Installing NEWSRDR Table_2-1_(Cont.)__NEWSRDR_system_logical_names________ Logical_Name____________Meaning________________________ 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. NEWSRDR_ORGANIZATION The name of the organization to be used in the "Organization:" header in news articles. Optional. NEWSRDR_SERVER The Internet node name of the NNTP news server to be used for NEWS sessions. NEWSRDR_GMT_OFFSET A VMS delta time string specifying the time differential between local time and Universal Coordinated Time. NEWSRDR_US_DST_ZONE Either TRUE or FALSE, depending on whether your locality observes U.S. standard daylight ________________________savings_time.__________________ 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. 2-4 Installing NEWSRDR __________________________________________________________________ 2.1 Creating the NEWSRDR Image 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: $ @LINK 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. __________________________________________________________________ 2.2 Compiling NEWSRDR from Sources 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: $ @COMPILE Then follow the compilation with the link step described in Section 2.1. __________________________________________________________________ 2.3 Help Library 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: $ DEFINE/SYSTEM NEWSRDR_HELP LOCAL_STUFF:[NEWSRDR]NEWSRDR_HELP.HLB 2-5 Installing NEWSRDR __________________________________________________________________ 2.4 On-Line Documentation 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. __________________________________________________________________ 2.5 Privileges Required 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. 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 except NETMBX 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. 2-6 Installing NEWSRDR ___________________________ 2.5.1 EXQUOTA and User Profiles 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 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. __________________________________________________________________ 2.6 Other User Requirements 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. 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. __________________________________________________________________ 2.7 Full-Screen Output 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. 2-7 Installing NEWSRDR __________________________________________________________________ 2.8 Callable Editors NEWSRDR can use any callable editor for message composition that meets the following calling standard: o The callable editor's shareable library name must be xxxSHR.EXE, where "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. o 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. 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 NEWSRDR User's Guide for further information. __________________________________________________________________ 2.9 VMS MAIL Interface 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. A further assumption is that the Internet mailer package used at your site includes a VMS MAIL "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 2-8 Installing NEWSRDR to any address specified when a user mails a message using NEWSRDR. __________________________________________________________________ 2.10 Character Conversion Support 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. 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: 1 Compile the C module (object code is provided for those without C compilers): $ CC KANJI_CONVERSION 2 Create the shareable library image: $ LINK/SHARE/NOTRACE KANJI_CONVERSION,SYS$INPUT:/OPT UNIVERSAL=NETWORK_TO_LOCAL,LOCAL_TO_NETWORK 3 Place the image in SYS$LIBRARY, define the appropriate NEWSRDR logical name and INSTALL the image: $ COPY KANJI_CONVERSION.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE $ DEFINE/SYSTEM/EXEC NEWSRDR_CHARACTER_CONVERSION - _$ SYS$SHARE:KANJI_CONVERSION.EXE $ INSTALL CREATE NEWSRDR_CHARACTER_CONVERSION/OPEN/SHARE/HEADER 2-9 Installing NEWSRDR 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. You only need to INSTALL the character conversion library if NEWSRDR is installed with privileges. __________________________________________________________________ 2.11 Establishing Your Time Zone This is only required if NEWSRDR_DO_DATE is defined TRUE. 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: $ DEFINE/SYSTEM NEWSRDR_GMT_OFFSET "-0 05:00:00" The minus sign indicates that Eastern time is 5 hours behind GMT. 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. 2-10 Installing NEWSRDR __________________________________________________________________ 2.12 Name Conversion Support 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. 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: 1 Edit and compile the C module, or develop your own module in another language that provides the same interface. 2 Create the shareable library image: $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT UNIVERSAL=INIT,CONVERT,CLEANUP 3 Place the resulting image in SYS$LIBRARY, define the appropriate NEWSRDR logical name, and INSTALL the image: $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE $ DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION SYS$SHARE:library.EXE $ INSTALL CREATE NEWSRDR_NAME_CONVERSION/OPEN/SHARE/HEADER 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: $ DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION MX_SITE_NAME_CONVERSION Refer to the sample code provided for further information on the name conversion interface. 2-11 Installing NEWSRDR __________________________________________________________________ 2.13 Address Conversion Support 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. 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: 1 Edit and compile the C module, or develop your own module in another language that provides the same interface. 2 Create the shareable library image: $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT UNIVERSAL=INIT,CONVERT,CLEANUP 3 Place the resulting image in SYS$LIBRARY, define the appropriate NEWSRDR logical name, and INSTALL the image: $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE $ DEFINE/SYSTEM/EXEC NEWSRDR_ADDRESS_CONVERSION SYS$SHARE:library.EXE $ INSTALL CREATE NEWSRDR_ADDRESS_CONVERSION/OPEN/SHARE/HEADER Refer to the sample code provided for further information on the address conversion interface. 2-12 Installing NEWSRDR __________________________________________________________________ 2.14 Installing NEWSRDR for Personal Use 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). 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. 2-13