                                   $           NEWSRDR Installation Guide                   September , 1992    ?           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.   9           Operating System and Version: VMS V5.0 or later   4           Software Version:             NEWSRDR V4.0                 Matthew Madison            TGV, Inc.             Santa Cruz, California                                             "           ________________________           15 September 1992   =           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.   6           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:  9           DEC                   ULTRIX                VAX #           VAXcluster            VMS         |9        |  MultiNet is a registered trademark of TGV, Inc.              __________8           Copyright 1992 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-4   A                 _________________________________________________ A                 2.2   HELP LIBRARY                            2-4   A                 _________________________________________________ A                 2.3   PRIVILEGES REQUIRED                     2-5   A                 _________________________________________________ A                 2.4   OTHER USER REQUIREMENTS                 2-5   A                 _________________________________________________ A                 2.5   FULL-SCREEN OUTPUT                      2-5     A                                                               iii                     Contents      A                 _________________________________________________ A                 2.6   CALLABLE EDITORS                        2-6   A                 _________________________________________________ A                 2.7   VMS MAIL INTERFACE                      2-6   A                 _________________________________________________ A                 2.8   CHARACTER CONVERSION SUPPORT            2-7   A                 _________________________________________________ A                 2.9   ESTABLISHING YOUR TIME ZONE             2-8   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 VMS/ULTRIX Connection, 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  (                $ 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.       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:  H                $ @SYS$UPDATE:VMSINSTAL NETLIB disk:[directory] OPTIONS N  >           Once NETLIB has been installed, it should be started4           by invoking its startup command procedure:  ,                $ @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:  )                $ 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):  5                $ BACKUP disk:[dir]NETLIBvvn.B/SAVE [] %                $ @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 [-]$                $ 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 a file containing a ?                                      message) that is displayed ;                                      whe NEWSRDR starts up.   =           NEWSRDR_BANG_ADDRESS       controls whether NEWSRDR 9                                      generates UUCP bang- 9                                      format addresses for >                                      From and Reply-To headers=                                      (as opposed to user@host ?                                      format). Default is FALSE.   =           NEWSRDR_BANG_PATH          controls whether NEWSRDR 9                                      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_DO_DATE            controls whether NEWSRDR ;                                      generates its own Date ?                                      headers. Default is FALSE.     A                                                               2-1                     Installing NEWSRDR      A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name_______________Meaning_____________________   =           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. Should9                                      only be set to FALSE 8                                      if your NNTP server<                                      aborts when it receives9                                      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.  9           NEWSRDR_INITIAL_GROUPS     a list of newsgroups <                                      that new 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 7                                      and news articles.         
           2-2          A                                                Installing NEWSRDR       A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name_______________Meaning_____________________   9           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 the4                                      mail node name.  4           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 string8                                      specifying the time9                                      differential between =                                      local time and Universal 6                                      Coordinated Time.                A                                                               2-3                     Installing NEWSRDR      A           Table_2-1_(Cont.)__NEWSRDR_system_logical_names________   A           Logical_Name_______________Meaning_____________________   :           NEWSRDR_US_DST_ZONE        Either TRUE or FALSE,>                                      depending on whether your;                                      locality observes U.S. >                                      standard daylight savingsA           ___________________________time._______________________o    9           The file NEWSRDR_STARTUP.COM, supplied with thes?           distribution kit, contains sample commands needed fore?           defining these logical names and performing the other0?           tasks needed to make NEWSRDR available on the system.0=           You should edit that file as needed for your system 9           and include it in your system startup sequence.   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@           Berkeley socket library (if it supports one), you must>           edit LINK.COM first to include the necessary library9           references appropriate for your TCP/IP package.o  L           __________________________________________________________________      2.2    Help Library  7           The help library for NEWSRDR may be placed inl;           SYS$HELP, or, if you define logical name NEWSRDR_t@           HELP to be the full file specification of the library,3           anywhere else on the system. For example:   Q                $ DEFINE/SYSTEM NEWSRDR_HELP LOCAL_STUFF:[NEWSRDR]NEWSRDR_HELP.HLB   
           2-49 a  e    A                                                Installing NEWSRDR     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 foreignI>           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.EXEM?           (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 uses:           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 memoryA8           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.G  :           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 bei#           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.  A                                                               2-5  _  _               Installing NEWSRDR    L           __________________________________________________________________      2.6    Callable Editors  9           NEWSRDR can use any callable editor for messageE@           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 twoc<              arguments. If there are optional arguments, the?              xxx$EDIT routine must not rely on having more thanN#              two arguments present.t  >           The Digital-supplied editors TPU, EDT, and TECO, and=           the (layered product) VAX Language-Sensitive Editor >           (LSE) all follow this calling standard. Editors that=           do not qualify as callable can be set up as spawneda@           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.   L           __________________________________________________________________      2.7    VMS MAIL Interface  ?           NEWSRDR uses the callable MAIL interface to send mails<           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 protocolP?           prefix used on your system, including the terminating'>           percent-sign. This prefix is automatically prepended  
           2-6          A                                                Installing NEWSRDR       >           to any address specified when a user mails a message           using 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 toi?           differing Kanji representations), you can accommodate >           the network character representation by installing a=           shareable library on the system containing routinest6           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   0           2  Create the shareable library image:  F                   $ LINK/SHARE/NOTRACE KANJI_CONVERSION,SYS$INPUT:/OPT>                    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 thet              image:   K                   $ COPY KANJI_CONVERSION.EXE SYS$COMMON:[SYSLIB]/PROT=W:RE E                   $ DEFINE/SYSTEM/EXEC NEWSRDR_CHARACTER_CONVERSION - 7                   _$     SYS$SHARE:KANJI_CONVERSION.EXETQ                   $ INSTALL CREATE NEWSRDR_CHARACTER_CONVERSION/OPEN/SHARE/HEADER_  A                                                               2-7  v  d               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 command2           procedure provided with the NEWSRDR kit.  ;           You only need to INSTALL the character conversionr:           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.n  @           Two logical names control the way date/time stamps are=           generated by NEWSRDR for articles posted by NEWSRDRp:           users. NEWSRDR_GMT_OFFSET should be defined as a;           VMS delta time specification preceded by either aA>           plus sign or a minus sign. This value represents the<           time differential between local time and Universal=           Coordinated Time (also called Greenwich Mean Time).g=           For the U.S. Eastern time zone, you would define itb
           as:i  ?                $ DEFINE/SYSTEM NEWSRDR_GMT_OFFSET "-0 05:00:00"   ?           The minus sign indicates that Eastern time is 5 hours            behind GMT.T  @           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.T    
           2-8          A                                                Installing NEWSRDR     L           __________________________________________________________________  !    2.10   Name Conversion Supportl  @           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 article            headers.  ?           An example of a module containing the routines neededn=           to support such conversions is provided in the file ?           NAME_CONVERSION.C as part of the distribution kit. Tos6           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:  A                   $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT 1                    UNIVERSAL=INIT,CONVERT,CLEANUPa                    <ctrl/Z>_  =           3  Place the resulting image in SYS$LIBRARY, define >              the appropriate NEWSRDR logical name, and INSTALL              the image:s  B                   $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:RET                   $ DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION SYS$SHARE:library.EXEL                   $ 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 conversion >           library for use with Message Exchange, you need only<           define a logical name to use the same library with           NEWSRDR:  S                $ DEFINE/SYSTEM/EXEC NEWSRDR_NAME_CONVERSION MX_SITE_NAME_CONVERSION   7           Refer to the sample code provided for further 7           information on the name conversion interface.   A                                                               2-9                     Installing NEWSRDR    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<           characters in addresses), you can install your own>           address conversion routine to perform this function.  ?           An example of a module containing the routines neededR=           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.   0           2  Create the shareable library image:  A                   $ LINK/SHARE/NOTRACE library.OBJ,SYS$INPUT:/OPT 1                    UNIVERSAL=INIT,CONVERT,CLEANUP                     <ctrl/Z>S  =           3  Place the resulting image in SYS$LIBRARY, defineg>              the appropriate NEWSRDR logical name, and INSTALL              the image:A  B                   $ COPY library.EXE SYS$COMMON:[SYSLIB]/PROT=W:REW                   $ DEFINE/SYSTEM/EXEC NEWSRDR_ADDRESS_CONVERSION SYS$SHARE:library.EXElO                   $ INSTALL CREATE NEWSRDR_ADDRESS_CONVERSION/OPEN/SHARE/HEADER   7           Refer to the sample code provided for furtherD:           information on the address conversion interface.                   2-10 u  s    A                                                Installing NEWSRDR     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 thee;           NEWSRDR image as described above, place the image ?           and the help library in directories you own, and editl>           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 