                                       $           NEWSRDR Installation Guide                 October, 1993       ?           This manual describes the installation of NEWSRDR, an 1           NNTP-based news reader for VMS systems.         A           Revision/Update Information:  This is a revised manual.   >           Operating System and Version: VAX/VMS V5.0 or later;A                                         OpenVMS AXP V1.0 or later   4           Software Version:             NEWSRDR V4.5                 Matthew Madison            MadGoat Software                                                 "           ________________________           09 October 1993   =           Permission is granted to copy and redistribute this *           document for no commercial gain.  ?           The information in this document is subject to change 9           without notice and should not be construed as a 9           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:  8           AXP                DEC                 OpenVMS            VAX                VMS  9           MultiNet is a registered trademark of TGV, Inc.              __________>           Copyright 1992, 1993 Matthew D. Madison. All Rights           Reserved.                        A           _______________________________________________________              Contents  A                 _________________________________________________ A                 PREFACE                                         v   A           _______________________________________________________ A           CHAPTER 1  INSTALLING NETLIB                        1-1   A                 _________________________________________________ 3                 1.1   DETERMINING WHETHER NETLIB IS A                       INSTALLED                               1-1   A                 _________________________________________________ A                 1.2   INSTALLING NETLIB SYSTEM-WIDE           1-2   A                 _________________________________________________ A                 1.3   PERSONAL NETLIB INSTALLATION            1-2   A                 1.3.1     Personal NETLIB Restriction  ___    1-3     A           _______________________________________________________ A           CHAPTER 2  INSTALLING NEWSRDR                       2-1   A                 _________________________________________________ A                 2.1   CREATING THE NEWSRDR IMAGE              2-5   A                 _________________________________________________ A                 2.2   HELP LIBRARY                            2-5   A                 _________________________________________________ A                 2.3   PRIVILEGES REQUIRED                     2-5   A                 _________________________________________________ A                 2.4   OTHER USER REQUIREMENTS                 2-6   A                 _________________________________________________ A                 2.5   FULL-SCREEN OUTPUT                      2-6     A                                                               iii                     Contents          A                 _________________________________________________ A                 2.6   CALLABLE EDITORS                        2-6   A                 _________________________________________________ A                 2.7   VMS MAIL INTERFACE                      2-7   A                 _________________________________________________ A                 2.8   CHARACTER CONVERSION SUPPORT            2-8   A                 _________________________________________________ A                 2.9   ESTABLISHING YOUR TIME ZONE             2-9   A                 _________________________________________________ A                 2.10  NAME CONVERSION SUPPORT                 2-9   A                 _________________________________________________ A                 2.11  ADDRESS CONVERSION SUPPORT             2-10   A                 _________________________________________________ A                 2.12  INSTALLING NEWSRDR FOR PERSONAL USE    2-11     A           _______________________________________________________            TABLES  A                 2-1       NEWSRDR system logical names  __    2-1                                        iv                   A           _______________________________________________________              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.  L           __________________________________________________________________             Intended Audience   5           This manual is intended for system managers <           responsible for installing and setting up NEWSRDR.  L           __________________________________________________________________             Document Structure  ;           This document consists of two chapters. Chapter 1 ;           describes the installation of NETLIB, the network @           interface library used by NEWSRDR. Chapter 2 describes8           the installation and configuration of NEWSRDR.  L           __________________________________________________________________             Related Documents   ?           The NEWSRDR User's Guide describes how to use NEWSRDR #           and all NEWSRDR commands.   ?           Internet RFC 1036, Standard for Interchange of USENET 8           Messages explains the structure of USENET news<           articles. RFC 977, Network News Transfer Protocol,=           describes NNTP news service. The Internet RFC's are 7           available via anonymous FTP from NIC.DDN.MIL.       A                                                                 v                      A           _______________________________________________________       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.   L           __________________________________________________________________  1    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  4                            $ SHOW LOGICAL NETLIB_DIR7                            $ SHOW LOGICAL NETLIB_SHRXFR 4                            $ 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.       A                                                               1-1                     Installing NETLIB         L           __________________________________________________________________  '    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:  T                            $ @SYS$UPDATE:VMSINSTAL NETLIB disk:[directory] OPTIONS N  >           Once NETLIB has been installed, it should be started4           by invoking its startup command procedure:  8                            $ @SYS$STARTUP:NETLIB_STARTUP  8           This should be done from a suitably privileged5           account, before you try to install NEWSRDR.   L           __________________________________________________________________  &    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:  5                            $ CREATE/DIRECTORY [.TEMP] 0                            $ 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):  A                            $ BACKUP disk:[dir]NETLIBvvn.B/SAVE [] 1                            $ @NETLIB_USER_INSTALL   ;           Answer the questions from the installation script 8           and the NETLIB files will be created. Once the<           installation procedure is complete, you can delete.           the files and the working directory:  
           1-2          A                                                 Installing NETLIB           ,                            $ SET DEFAULT [-]0                            $ 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.                                                          A                                                               1-3                      A           _______________________________________________________       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:   A           Table_2-1__NEWSRDR_system_logical_names________________   A           Logical_Name____________Meaning________________________   >           NEWSRDR_ANNOUNCE        a message (or a pointer to aA                                   file containing a message) that A                                   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. 3                                   Default is FALSE.     A                                                               2-1                     Installing NEWSRDR          A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name____________Meaning________________________   ;           NEWSRDR_DISALLOW_       when defined, the user is <           POSTING                 prevented from posting any+                                   articles.   :           NEWSRDR_DO_DATE         controls whether NEWSRDRA                                   generates its own Date headers. 3                                   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 4                                   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 of3                                   your NNTP server.                     
           2-2          A                                                Installing NEWSRDR           A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name____________Meaning________________________   =           NEWSRDR_FAKE_           when TRUE, NEWSRDR does its >           NEWGROUPS               own new newsgroup discovery.>                                   Default is FALSE. Can be setA                                   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 5                                   option is disabled.   ?           NEWSRDR_INITIAL_        a list of newsgroups that new >           GROUPS                  users will get subscribed to>                                   automatically the first time3                                   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 and0                                   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.,1                                   "MX%", "INET%")            .|            |?           N|WSRDR_NO_XHDR         disables the attempted use of A            |                      the XHDR extended NNTP command.     A                                                               2-3                     Installing NEWSRDR          A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name____________Meaning________________________   =           NEWSRDR_NODE_NAME       the node name of the systemE<                                   for news purposes. This is;                                   generally the same as the,@                                   Internet node name or the mail,                                   node name.  A           NEWSRDR_ORGANIZATION    The name of the organization toM@                                   be used in the "Organization:":                                   header in news articles.+                                   Optional.o  ?           NEWSRDR_SERVER          The Internet node name of the A                                   NNTP news server to be used fort0                                   NEWS sessions.  9           NEWSRDR_GMT_OFFSET      A VMS delta time stringi5                                   specifying the timei<                                   differential between local@                                   time and Universal Coordinated'                                   Time.r  A           NEWSRDR_US_DST_ZONE     Either TRUE or FALSE, depending :                                   on whether your localityA                                   observes U.S. standard daylight A           ________________________savings_time.__________________i  9           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 systema9           and include it in your system startup sequence.y        
           2-4e .  d    A                                                Installing NEWSRDR         L           __________________________________________________________________  $    2.1    Creating the NEWSRDR Image  8           The NEWSRDR package comes with the object code9           required to create the NEWSRDR image. A command_<           procedure called LINK.COM is provided for creating           the image:  "                            $ @LINK  8           If you wish to link NEWSRDR with your TCP/IP's;           B|rkeley socket library (if it supports one), you >           m|y need to recompile SERVER_SOCKET.C as appropriate;           f|r your TCP/IP package, and you may also need to_@           e|it LINK.COM to link against the necessary library or           l|braries.  L           __________________________________________________________________      2.2    Help Library  7           The help library for NEWSRDR may be placed inI;           SYS$HELP, or, if you define logical name NEWSRDR__@           HELP to be the full file specification of the library,3           anywhere else on the system. For example:   ]                            $ DEFINE/SYSTEM NEWSRDR_HELP LOCAL_STUFF:[NEWSRDR]NEWSRDR_HELP.HLBR  L           __________________________________________________________________      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.  9           NEWSRDR uses callable MAIL and the MAIL foreign_>           protocol interface to send mail messages. Therefore,9           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 atS;           the start of execution. If you do not wish to use_  A                                                               2-5I R  E               Installing NEWSRDR          :           NEWSRDR to send mail, you do not need to install"           NEWSRDR with privileges.  L           __________________________________________________________________  !    2.4    Other User Requirements   7           NEWSRDR has no extensive disk quota or memory 8           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 alsot?           created in SYS$SCRATCH. Since news articles generally ?           do not exceed a few hundred lines, this should not be_#           a problem for most users.   L           __________________________________________________________________      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.  L           __________________________________________________________________      2.6    Callable Editors  9           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 inA              SYS$SHARE or must have an exec-mode logical pointingc&              to the library elsewhere.  
           2-6_ _  _    A                                                Installing NEWSRDR           >           o  The shareable library must contain an entry point=              which called xxx$EDIT, which must take the inputS;              file-spec and output file-spec, both charactern;              strings passed by descriptor, as the first twoN<              arguments. If there are optional arguments, the?              xxx$EDIT routine must not rely on having more thanu#              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 the7           NEWSRDR User's Guide for further information.n  L           __________________________________________________________________      2.7    VMS MAIL Interface  ?           NEWSRDR uses the callable MAIL interface to send mailn<           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 handle2           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.            A                                                               2-7L D                  Installing NEWSRDR        L           __________________________________________________________________  &    2.8    Character Conversion Support  >           If your news network uses a character representation<           for its articles that requires conversion from the9           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 routinesi6           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):  3                               $ CC KANJI_CONVERSIONc  0           2  Create the shareable library image:  R                               $ LINK/SHARE/NOTRACE KANJI_CONVERSION,SYS$INPUT:/OPTJ                                UNIVERSAL=NETWORK_TO_LOCAL,LOCAL_TO_NETWORK'                                <ctrl/Z>_  7           3  Place the image in SYS$LIBRARY, define the =              appropriate NEWSRDR logical name and INSTALL the               image:i  W                               $ COPY KANJI_CONVERSION.EXE SYS$COMMON:[SYSLIB]/PROT=W:REyQ                               $ DEFINE/SYSTEM/EXEC NEWSRDR_CHARACTER_CONVERSION -$C                               _$     SYS$SHARE:KANJI_CONVERSION.EXE[]                               $ INSTALL CREATE NEWSRDR_CHARACTER_CONVERSION/OPEN/SHARE/HEADERw  ?           Note that you must do this from a suitably privilegeds@           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 command2           procedure provided with the NEWSRDR kit.  
           2-8t         A                                                Installing NEWSRDR           ;           You only need to INSTALL the character conversion :           library if NEWSRDR is installed with privileges.  L           __________________________________________________________________  %    2.9    Establishing Your Time Zone   =           This is only required if NEWSRDR_DO_DATE is defined            TRUE.E  @           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 ita
           as:m  K                            $ DEFINE/SYSTEM NEWSRDR_GMT_OFFSET "-0 05:00:00"   ?           The minus sign indicates that Eastern time is 5 hours            behind GMT.s  @           The logical name NEWSRDR_US_DST_ZONE should be defined9           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 3           the beginning and end of your DST period.N  L           __________________________________________________________________  !    2.10   Name Conversion Support   @           If your site does not use VMS usernames for addressing8           local users in network mail, you can install a=           shareable library containing a routine that NEWSRDR 6           will call on to perform username-to-mailname;           conversions for addresses that it puts in articlem           headers.  A                                                               2-9                     Installing NEWSRDR          ?           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. Toh6           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.-  0           2  Create the shareable library image:  M                               $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT =                                UNIVERSAL=INIT,CONVERT,CLEANUP '                                <ctrl/Z>n  A           3  Place the resulting image in SYS$LIBRARY, define thes>              appropriate NEWSRDR logical name, and INSTALL the              image:   N                               $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE`                               $ DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION SYS$SHARE:library.EXEX                               $ INSTALL CREATE NEWSRDR_NAME_CONVERSION/OPEN/SHARE/HEADER  <           The interface used by NEWSRDR is identical to that@           used by Rensselaer's Message Exchange E-mail software.9           If you already have installed a name conversionm>           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_CONVERSIONe  7           Refer to the sample code provided for furtherP7           information on the name conversion interface.w  L           __________________________________________________________________  $    2.11   Address Conversion Support  8           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             2-10         A                                                Installing NEWSRDR           <           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.e  0           2  Create the shareable library image:  M                               $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPTc=                                UNIVERSAL=INIT,CONVERT,CLEANUPp'                                <ctrl/Z>N  A           3  Place the resulting image in SYS$LIBRARY, define the >              appropriate NEWSRDR logical name, and INSTALL the              image:l  N                               $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:REc                               $ DEFINE/SYSTEM/EXEC NEWSRDR_ADDRESS_CONVERSION SYS$SHARE:library.EXEr[                               $ INSTALL CREATE NEWSRDR_ADDRESS_CONVERSION/OPEN/SHARE/HEADER   7           Refer to the sample code provided for further :           information on the address conversion interface.  L           __________________________________________________________________  -    2.12   Installing NEWSRDR for Personal Use   <           If you are not the system manager, you can install8           NEWSRDR for your own use, with the restriction=           that you may not be able to send mail using NEWSRDR 5           (depending on your site's E-mail software).   9           To install NEWSRDR for your own use, create thet;           NEWSRDR image as described above, place the imagee?           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.  A                                                              2-11 