NEWSRDR Installation Guide April, 1993 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.2 or later; OpenVMS Alpha AXP V1.0 or later Software Version: NEWSRDR V4.2 Matthew Madison TGV, Inc. Santa Cruz, California ________________________ 23 April 1993 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 and TGV, Inc. 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 ©1992, 1993 Matthew D. Madison. All Rights Reserved. _______________________________________________________ Contents _________________________________________________ PREFACE v _______________________________________________________ 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-4 _________________________________________________ 2.2 HELP LIBRARY 2-5 _________________________________________________ 2.3 PRIVILEGES REQUIRED 2-5 _________________________________________________ 2.4 OTHER USER REQUIREMENTS 2-5 _________________________________________________ 2.5 FULL-SCREEN OUTPUT 2-6 iii Contents _________________________________________________ 2.6 CALLABLE EDITORS 2-6 _________________________________________________ 2.7 VMS MAIL INTERFACE 2-7 _________________________________________________ 2.8 CHARACTER CONVERSION SUPPORT 2-7 _________________________________________________ 2.9 ESTABLISHING YOUR TIME ZONE 2-8 _________________________________________________ 2.10 NAME CONVERSION SUPPORT 2-9 _________________________________________________ 2.11 ADDRESS CONVERSION SUPPORT 2-10 _________________________________________________ 2.12 INSTALLING NEWSRDR FOR PERSONAL USE 2-11 _______________________________________________________ TABLES 2-1 NEWSRDR system logical names __ 2-1 iv _______________________________________________________ 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. v _______________________________________________________ 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 Rensselaer. 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 TCPware, and TGV MultiNet. __________________________________________________________________ 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, 012 for NETLIB V1.2): $ 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. | N|WSRDR_DISABLE_USER_ when TRUE, users cannot set R|PLY_TO their own Reply-To headers. | Default is FALSE. 2-1 Installing NEWSRDR T|ble_2-1_(Cont.)__NEWSRDR_system_logical_names________ | L|gical_Name____________Meaning________________________ | N|WSRDR_DISALLOW_ when defined, the user is P|STING 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 T|ble_2-1_(Cont.)__NEWSRDR_system_logical_names________ | L|gical_Name____________Meaning________________________ | N|WSRDR_FAKE_ when TRUE, NEWSRDR does its N|WGROUPS 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_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. 2-3 Installing NEWSRDR Table_2-1_(Cont.)__NEWSRDR_system_logical_names________ Logical_Name____________Meaning________________________ 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.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 2-4 Installing NEWSRDR If you wish to link NEWSRDR with your TCP/IP's Berkeley socket library (if it supports one), you must edit LINK.COM first to include the necessary library references appropriate for your TCP/IP package. __________________________________________________________________ 2.2 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.3 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.4 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. 2-5 Installing NEWSRDR 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.5 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.6 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-6 Installing NEWSRDR __________________________________________________________________ 2.7 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 to any address specified when a user mails a message using NEWSRDR. __________________________________________________________________ 2.8 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 2-7 Installing NEWSRDR 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 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.9 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. 2-8 Installing NEWSRDR 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 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 2-9 Installing NEWSRDR The interface used by NEWSRDR is identical to that used by Rensselaer'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 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: 2-10 Installing NEWSRDR $ 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 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-11