DECUS UUCP (VMSNET Software) Version 1.3 System Manager's Guide January 31, 1991 (Winter 1991 Distribution) The VMSnet Working Group DECUS VAX Systems SIG Jamie E. Hanrahan Simpact Associates 9210 Sky Park Court San Diego, CA 92123 +1 619-565-1865 x1116 jeh@dcs.simpact.com Tom Allebrandi II Mark Pizzolato Inland Steel Research Labs 1558 Fernside Street East Chicago, IN Redwood City CA 94061 +1 219-399-6306 +1 415-369-9366 allebrandi@inland.com mark@infopiz.com ..!decwrl!simpact!inland!allebrandi ...!decwrl!infopiz!mark DECUS UUCP Version 1.3 System Manager's Guide Page ii This document was prepared with DSR, Digital Standard Runoff. The .MEM file supplied is formatted for correct printing on line printers and other devices that support the "return with no line feed" method of underlining. 60 lines per page (the intent is for a half inch margin at top and bottom) and 65 characters per line (allowing for one-inch side margins, even at 10 characters per inch) are used. A few long lines appear in examples. If your printer does not provide a satisfactory left margin, set your default directory to [.DOC] and type "@[-.BIN]DSR USRGD12B /RIGHT=n" at the DCL prompt; this will produce a new .MEM file with the text shifted right by the specified amount. You can also use the /BACKSPACE qualifier to cause DSR to use the backspace method of underlining. IMPORTANT! Users of prior versions of this software should be sure to read Chapter 1, "What's New in This Release". | | Significant changes from the 1.1 edition of this document are | identified by change bars. ___ Those who are familiar with uucp under Unix should not assume that all of their experience is transferable. For example, configuration files (control and system) are different here; chat scripts are very different. (We didn't write all of this text for nothing!) VAX and VMS are trademarks of Digital Equipment Corporation. Hayes is a registered trademark of Hayes Microcomputer Products, Inc. Unix is, as we all know very well by now, a registered trademark of AT&T. THIS DOCUMENT IS IN THE PUBLIC DOMAIN. DECUS UUCP Version 1.3 System Manager's Guide Page iii CONTENTS CHAPTER 0 INTRODUCTION 0.1 How To Read This Document . . . . . . . . . . . . 0-1 0.2 Special Note For Cluster Users . . . . . . . . . . 0-2 0.3 How To Get More Help . . . . . . . . . . . . . . . 0-2 0.4 On-Line Help . . . . . . . . . . . . . . . . . . . 0-4 0.5 Squeaky Wheels Get The Grease . . . . . . . . . . 0-5 CHAPTER 1 WHAT'S NEW IN THIS RELEASE (1.2X) 1.1 Changes In Configuration Files . . . . . . . . . . 1-1 1.2 Example Configuration Files . . . . . . . . . . . 1-1 1.3 New Facilities . . . . . . . . . . . . . . . . . . 1-2 1.4 The Mailer . . . . . . . . . . . . . . . . . . . . 1-2 1.5 UUCP . . . . . . . . . . . . . . . . . . . . . . . 1-5 1.6 NEWS . . . . . . . . . . . . . . . . . . . . . . . 1-8 CHAPTER 2 CONCEPTS AND TERMINOLOGY 2.1 The Basics . . . . . . . . . . . . . . . . . . . . 2-1 2.2 What Is DECUS UUCP? . . . . . . . . . . . . . . . 2-2 2.3 How Do I Apply To Join The Network? . . . . . . . 2-2 2.4 How Are Mail And News Supported? . . . . . . . . . 2-3 2.5 Netnews, Usenet, And VMSnet . . . . . . . . . . . 2-3 2.6 Internet... . . . . . . . . . . . . . . . . . . . 2-4 2.7 ...And Beyond . . . . . . . . . . . . . . . . . . 2-5 CHAPTER 3 INSTALLING THE FILES 3.1 "Example" Configuration Files And Command Procedures . . . . . . . . . . . . . . . . . . . . 3-1 3.2 Space Requirements . . . . . . . . . . . . . . . . 3-2 3.3 ANU NEWS . . . . . . . . . . . . . . . . . . . . . 3-3 CHAPTER 4 MODEMS AND MULTIPLEXERS 4.1 Setting Terminal Characteristics . . . . . . . . . 4-1 4.2 Data Path Requirements . . . . . . . . . . . . . . 4-4 4.3 Requirements For Serial Ports . . . . . . . . . . 4-5 4.4 Requirements For Modems . . . . . . . . . . . . . 4-6 4.5 RS232 Control Signals . . . . . . . . . . . . . . 4-9 4.6 Testing . . . . . . . . . . . . . . . . . . . . 4-12 4.7 Summary . . . . . . . . . . . . . . . . . . . . 4-13 CHAPTER 5 ARRANGING FOR UUCP CONNECTIONS 5.1 Choose Your Host Name . . . . . . . . . . . . . . 5-1 DECUS UUCP Version 1.3 System Manager's Guide Page iv 5.2 Getting A Connection . . . . . . . . . . . . . . . 5-2 5.3 Exchange Login Procedures . . . . . . . . . . . . 5-4 CHAPTER 6 CONFIGURING DECUS UUCP 6.1 Create The Uucp Username(s) . . . . . . . . . . . 6-1 6.2 Edit UUCP_SYSTARTUP.COM . . . . . . . . . . . . . 6-4 6.3 Create Your UUCP Map Entry . . . . . . . . . . . . 6-4 6.4 Create The UUCP Control File . . . . . . . . . . . 6-4 6.5 Create The UUCP Systems File . . . . . . . . . . . 6-8 6.6 Script Files . . . . . . . . . . . . . . . . . . 6-16 6.7 Summary . . . . . . . . . . . . . . . . . . . . 6-18 CHAPTER 7 SCRIPT FILES 7.1 Script File Format . . . . . . . . . . . . . . . . 7-1 7.2 Script File Statements . . . . . . . . . . . . . . 7-2 7.3 Script Processing Details . . . . . . . . . . . . 7-4 7.4 Written Any Good Scripts Lately? . . . . . . . . . 7-9 CHAPTER 8 FINISHING AND TESTING THE INSTALLATION OF UUCP 8.1 Check SYSGEN Parameters . . . . . . . . . . . . . 8-1 8.2 File Protection . . . . . . . . . . . . . . . . . 8-1 8.3 Define UUCP Logical Names . . . . . . . . . . . . 8-1 8.4 Generating The Path Data Base . . . . . . . . . . 8-1 8.5 Start It Up . . . . . . . . . . . . . . . . . . . 8-2 8.6 Test It . . . . . . . . . . . . . . . . . . . . . 8-3 8.7 If The Call Doesn't Work . . . . . . . . . . . . . 8-3 8.8 Make It Automatic . . . . . . . . . . . . . . . . 8-4 8.9 Note For Cluster Users . . . . . . . . . . . . . . 8-4 8.10 Tell Your Users . . . . . . . . . . . . . . . . . 8-5 8.11 Tell The World . . . . . . . . . . . . . . . . . . 8-5 8.12 Tell Us . . . . . . . . . . . . . . . . . . . . . 8-5 8.13 Obtaining Current Maps . . . . . . . . . . . . . . 8-5 8.14 Adding More Neighbors . . . . . . . . . . . . . . 8-6 CHAPTER 9 REGISTERING AS AN INTERNET DOMAIN 9.1 Why Should I Become A Domain? . . . . . . . . . . 9-1 9.2 Why Do I Need A Forwarder? . . . . . . . . . . . . 9-2 9.3 How Do I Register? . . . . . . . . . . . . . . . . 9-3 9.4 What Then? . . . . . . . . . . . . . . . . . . . . 9-4 9.5 What If Another Machine In My Company Is Already Registered? . . . . . . . . . . . . . . . . . . 9-10 9.6 Domain Names: Machines Vs. Companies . . . . . . 9-11 9.7 Special Acknowledgement . . . . . . . . . . . . 9-12 CHAPTER 10 ADMINISTRATIVE TASKS FOR NEWS SUPPORT 10.1 Newsgroups -- What To Carry? . . . . . . . . . . 10-1 DECUS UUCP Version 1.3 System Manager's Guide Page v 10.2 Arranging For News Feeds . . . . . . . . . . . . 10-4 10.3 Feeding News To Other Sites . . . . . . . . . . 10-5 10.4 ANU News And DECUS Uucp . . . . . . . . . . . . 10-5 10.5 News System Configurations . . . . . . . . . . . 10-6 10.6 A Bit More About NNTP . . . . . . . . . . . . . 10-8 CHAPTER 11 INSTALLING AND INTEGRATING NEWS 11.1 The ANU News Distribution . . . . . . . . . . . 11-1 11.2 Documentation . . . . . . . . . . . . . . . . . 11-1 11.3 Installing News: Comments On Chapter 10 Of The News User's Guide . . . . . . . . . . . . . . . 11-2 11.4 Exchanging News With Other Sites (Batch Transfers) . . . . . . . . . . . . . . . . . . . 11-16 11.5 NNTP Client/Server Support . . . . . . . . . . 11-20 11.6 Start Up The Transfer Processes . . . . . . . . 11-20 APPENDIX A USING TELEBIT MODEMS A.1 Serial Port Requirements . . . . . . . . . . . . . A-1 A.2 Goals . . . . . . . . . . . . . . . . . . . . . . A-2 A.3 Modem Settings . . . . . . . . . . . . . . . . . . A-3 A.4 Setting It Up . . . . . . . . . . . . . . . . . . A-4 A.5 Control And Systems File Entries . . . . . . . . . A-5 A.6 Communicating With Other Telebits . . . . . . . . A-6 A.7 Compatibility Issues (old History) . . . . . . . . A-6 APPENDIX B PATHALIAS (UUCP MAP FILE FORMAT DETAILS) B.1 Description . . . . . . . . . . . . . . . . . . . B-1 B.2 Uucp Map File Format . . . . . . . . . . . . . . . B-1 B.3 Output Format . . . . . . . . . . . . . . . . . . B-6 B.4 Bugs And Deficiencies . . . . . . . . . . . . . . B-6 APPENDIX C UTILITIES C.1 Checkaddr . . . . . . . . . . . . . . . . . . . . C-2 C.2 Tail . . . . . . . . . . . . . . . . . . . . . . . C-3 C.3 Compress . . . . . . . . . . . . . . . . . . . . . C-5 C.4 Uurate - Report Transfer And Connect Times For Uucp Calls . . . . . . . . . . . . . . . . . . . . C-8 APPENDIX D ADDRESS FORMATS D.1 The Simple Cases . . . . . . . . . . . . . . . . . D-1 D.2 The Complex Cases . . . . . . . . . . . . . . . . D-3 APPENDIX E HOW IT WORKS E.1 The Basics . . . . . . . . . . . . . . . . . . . . E-1 DECUS UUCP Version 1.3 System Manager's Guide Page vi E.2 Details: B, X, C, And D Files . . . . . . . . . . E-2 E.3 Locks . . . . . . . . . . . . . . . . . . . . . . E-2 E.4 Unix Compatibility Issues . . . . . . . . . . . . E-2 APPENDIX F TROUBLESHOOTING F.1 UUCP.LOG . . . . . . . . . . . . . . . . . . . . . F-1 F.2 The Debug Log File . . . . . . . . . . . . . . . F-6 F.3 SYS$ERROR . . . . . . . . . . . . . . . . . . . . F-8 F.4 Status Files . . . . . . . . . . . . . . . . . . . F-9 F.5 UUXQT's Batch Log . . . . . . . . . . . . . . . . F-9 F.6 Other Sources Of Information . . . . . . . . . . . F-9 F.7 "Expected Problems" . . . . . . . . . . . . . . F-11 F.8 Restarting The Batch Jobs . . . . . . . . . . . F-12 F.9 "MicroVAX Crashes While Running DECUS Uucp" . . F-12 APPENDIX G SECURITY ISSUES G.1 Decus Uucp Security Provisions . . . . . . . . . . G-2 G.2 Things They Can Do To You . . . . . . . . . . . . G-5 G.3 Contrast With Unix Uucp . . . . . . . . . . . . . G-6 G.4 The Internet Worm . . . . . . . . . . . . . . . . G-7 G.5 Uucp Security History . . . . . . . . . . . . . . G-7 APPENDIX H WANT TO HELP? APPENDIX I CHANGES FROM VERSION 0.2 TO 1.1 I.1 Name Changes . . . . . . . . . . . . . . . . . . . I-1 I.2 Required Configuration Changes . . . . . . . . . . I-1 I.3 New Features . . . . . . . . . . . . . . . . . . I-2 I.4 Implementation Changes . . . . . . . . . . . . . . I-5 I.5 Bug Fixes . . . . . . . . . . . . . . . . . . . . I-6 APPENDIX J ACKNOWLEDGEMENTS J.1 Version 1.2 And 1.2A . . . . . . . . . . . . . . . J-1 J.2 Version 1.0 And 1.1 . . . . . . . . . . . . . . . J-1 J.3 Version 0.2 . . . . . . . . . . . . . . . . . . . J-2 CHAPTER 0 INTRODUCTION Welcome to the fourth distribution of DECUS uucp (formerly "VMSnet Software"), a package which allows VMS systems to exchange mail with other computers using the uucp 'g' protocol. This version (1.3) is being prepared for distribution via direct mail, the Fall '90 VAX Symposium Tape, and the DECUS Program Library. Previous versions appeared on earlier Symposium tapes. This version of DECUS uucp was built under VMS Version 5.2, and should run on any later version. To the best of our knowledge there is no code that depends on V5.2 features; it should be possible to relink the object files under any earlier point release of VMS Version 5. 0.1 How To Read This Document Read all of it. But not necessarily all at once. This document is less of a "user's guide", in the sense of instructions for end users, than a set of instructions to you, the prospective DECUS uucp site manager, for bringing up the package. [1] So most of the chapters here are instructions for "major steps" in the procedure, and the sections and subsections within each chapter break the major steps into small tasks. The appendices provide supplemental information for some of the _____ __ ________ steps. A quick scan of the table of contents will give you a good idea of what you're facing. ___ ____ There is no index in this manual, but don't forget that you have __ _______ it on-line!!! That means that you can use the SEARCH utility to find things. We have left News integration for the last chapters (not counting Appendices). You are strongly encouraged to get uucp mail working reliably before attempting to add News. ____________________ __ [1] One of the many things we need to provide is a set of instructions for end users: How to send network mail, for instance. Anyone who sends any text that we can incorporate in such a document will receive our gratitude and will be duly credited for their efforts. INTRODUCTION Page 0-2 How To Read This Document Do not expect to grasp all of this at one sitting, particularly if you are unfamiliar with uucp networking. Skim through it once, perhaps on a Friday afternoon, just for the highlights. Come back to it Monday or Tuesday and look at it again; there are, inevitably, a lot of "forward references" that won't be filled in until you've been through it a few times. | | | 0.2 Special Note For Cluster Users | | If you're running a VAXcluster (CI, NI, or mixed), the usual | setup is to run uucp on just one node. Other nodes will still be | able to send and receive uucp mail, but only one node will | actually be running the uucp processes that place and receive | calls. If you're using a traditional terminal multiplexer, the | "uucp node" will be the machine to which the modems are attached; | if your modems are on LAT ports it can be any machine that can | access the LAT box and has the other required resources. | | For now, perform all of the instructions on your intended "uucp | node". We'll have another "Note for Cluster Users" later on, to | tell you how to make uucp mail available on the other nodes. 0.3 How To Get More Help 0.3.1 Everything You Wanted To Know About Uucp (Under Unix, Though) _____ ____ ___ ______ We strongly urge you to purchase the books Using uucp and Usenet ________ ____ ___ ______ and Managing uucp and Usenet. These say nothing about running uucp on VMS; they are strictly for the Unix user and system manager (or "administrator", as they're known in that domain). [2] But if you are at all unfamiliar with uucp networking, these books will help put you on common speaking terms with the people with whom you will most likely be establishing your first uucp connections. All three of us have copies of both books, and refer to them often. The books may be ordered directly from the publisher: O'Reilly And Associates 981 Chestnut Street Newton, MA 02164 1-800-338-6887 1-617-527-1392 (in Massachusetts) They will accept phone orders using Visa, MC, and AmEx. Well-stocked technical or computer bookstores may also carry these titles. (Disclaimer: We have no financial interest in any part of this.) ____________________ [2] The publisher has expressed an interest in incorporating VMS-related material in future editions. INTRODUCTION Page 0-3 How To Get More Help If you have access to the documentation for a Unix, Ultrix, or similar system, look for a paper titled "Uucp Implementation _____________ _________ Description" by D. A. Nowitz. (Check the Supplementary Documents volumes, if present.) The article "HoneyDanBer UUCP -- Bringing Unix Systems into the Information Age" by Bill Rieken and Jim Webb has a very interesting description of the most recent Unix implementation of uucp. It appeared in Volume 1, Numbers 3 and 4 (May/June and _______ July/August, 1986) of ;login:, the journal of the Usenix Association. 0.3.2 Don't Call Us, At Least Not Very Often We really hate to have to say this, but we have to say this: WE, THE AUTHORS, CANNOT PROVIDE MUCH TELEPHONE SUPPORT FOR THIS SOFTWARE. Our respective employers do support these efforts, because network connections are good things to have and the work is related to the rest of what we do. But this is very much a "spare time" activity; it doesn't make any money. If we start getting phone calls to the extent that our real work is interfered with, we may be asked to stop working on DECUS uucp entirely, and to refuse all telephone calls relating to it. And we really would like to stay open to those (hopefully few) phone ______ calls that you just have to make when you really get stuck! ___ So, please: Exhaust all other avenues before calling us. Okay? Look at it this way: If you haven't had a uucp connection to your VMS machine in the past, it's doubtful that the world will end if you don't have one the day after you restore the distribution tape to disk. Go home, forget about it, and come back to it the next day. (If you're like us, the answer will come to you while you're brushing your teeth, or something.) If you're still stuck after a week or so (and other options -- see below -- haven't proven fruitful), go ahead and call. We ___ didn't say we couldn't provide any support, just that we can't take too much time away from our jobs to do so. ____ Of course, we'd love to hear success stories. But even "Hey! I got it running on the first try!" calls will be a problem if we start getting a dozen or two a day. When you do get connected, send us mail! 0.4 On-Line Help If you do need to ask us for help, there are ways to contact us other than by phone. INTRODUCTION Page 0-4 On-Line Help 0.4.1 Via The Network Of course if you could get connected you wouldn't need help, but... try to obtain a "guest" account on one of your neighbor machines, and use it to send mail to one (or all) of us. Our network addresses are listed on the front page. This will give you the fastest response, and probably a better response than if you just call by phone, at least if you have a problem we haven't seen before. 0.4.2 DECUServe You are urged to sign up with DECUServe, DECUS's dial-up on-line conferencing system. Topic 58 in the PUBLIC_DOMAIN_SOFTWARE conference is devoted to announcements, bug reports, and bug fixes relating to DECUS uucp, ANU News, related software, and sites running same. A query posted there will usually be answered within a day or two. To join DECUServe, send a note to DECUS -- DECUServe Processing 219 Boston Post Road, BPO2 Marlboro, MA 01752-1850 and ask for an application form. DECUServe's dialin numbers are in the Boston area, and are reachable via PC-Pursuit, so phone costs should not be prohibitive. 0.4.3 "Pageswapper" Notes System You may also, or instead, wish to acquire an account on Larry Kilgallen's "Pageswapper" VAXnotes system. This is free (except for phone line time charges). To obtain an account, call 1-617-262-6830 at 1200 bps and log in to account PAGESWAPPER (no password). You will be asked to fill out an on-line account application, and you will likely receive your username and password (by US Mail) in a week or two. Note 1211 in the "IO" conference on Pageswapper is dedicated to DECUS uucp, ANU News, and related issues. 0.4.4 For More Help And Updates After It's Running Once you can send and receive network mail, send mail to | vmsnet-request@drycas.club.cc.cmu.edu requesting to be placed on the "VMSnet mailing list". (Note that that's a hyphen, not an underscore, in "vmsnet-request".) To send items to the list itself, send mail to INTRODUCTION Page 0-5 On-Line Help | vmsnet@drycas.club.cc.cmu.edu and they'll be relayed to everyone else who has signed up. Once you have News running, if you carry the VMSnet newsgroup hierarchy (to be described), you can resign from the mailing list if you prefer, as the vmsnet.uucp newsgroup is gatewayed to the list. | | NOTE | | Once you have access to News or to the vmsnet ______ | mailing list, please send help requests there | rather than via personal mail to one (or all) of | us. | 0.5 Squeaky Wheels Get The Grease Now, having done our best to discourage certain types of ______ __ interruptions, we must say that we really do want those problem reports! If any aspect of this package doesn't work, please don't just put it aside and forget about it! We have found and fixed all the bugs that became evident in our test environments -- but obviously we can't test everything under all possible "real world" situations. We can only correct problems which are reported to us! This is even true -- or perhaps especially true -- of problems in this manual. Our goal is to make this software as easy to use as possible, and the manual plays a big part in that. The text here makes sense to us, but then we're obviously very familiar with the software being described. So any suggestions -- from pointing out typos, through ideas for organizational changes, to _______ text to be included in the next edition -- would be greatly appreciated. CHAPTER 1 WHAT'S NEW IN THIS RELEASE (1.3) | This chapter provides a brief description of the new features of | this version of DECUS uucp, relative to Version 1.2x. Changes in | 1.2 and 1.1 are described in Appendices. | | | 1.1 NEWS | | This DECUS uucp distribution includes ANU NEWS Version 6.0-2. | | | 1.2 Changes In Configuration Files | __ | We are happy to report that most sites should need to make no | changes in their configuration files to use DECUS uucp 1.3. (The | only exception will be sites that are still running V0.2; in that | case you should read the chapter on configuration files very | carefully.) | | There is one change required by the current version of News, | relative to News V5.7: If you've used nested quoting in your | NEWS_ADDRESS.CNF file, you'll have to change it, and strip off | the outer layer of quotes. For example, in the DECUS uucp world, | we used to say | | *@* "UUCP%""001@002""" | | but now we say | | *@* UUCP%"001@002" | | This change was actually required by NEWS 5.8, and all subsequent | versions. | | | 1.3 The Mailer | | Most of the changes in DECUS uucp V1.3 have to do with the mail | interface and related software. WHAT'S NEW IN THIS RELEASE (1.3) Page 1-2 | The Mailer | 1.3.1 Makepaths And PathProc | | The Makepaths procedure and the PathProc utility program have not | changed for this release. (That is, they have not changed from | version 1.2.) | | | 1.3.2 Pathalias | | Pathalias, the utility used to determine mail delivery routes | from the UUCP map files, has changed for this release. The new | version contains the latest source code from Peter Honeyman, the | Pathalias developer. | | This new version should be immune to the problem that occasionaly | sent the previous release into an infinite memory grabbing loop. | | | 1.3.3 UUCP_MAILSHR | | 1.3.3.1 To: Headers | | 1.3.3.1.1 To: Headers For Multiple Addressees - | | A side effect of a bug fix required some rework on the generation | of the To: header. A result of the change is that for outbound | mail, UUCP_MAILSHR will attempt to create an RFC 822 To: header | containing a list of addresses. Previously, when a single | message was sent to multiple people, the To: header in each copy | contained just the address of the person receiving it. | | When sending mail to more than one recipient, VAX Mail at its | discretion may choose to invoke UUCP_MAILSHR once passing all of | the target addresses, or many times passing a few addresses each | time. The list form of the To: header is created from only | those addresses which are passed in a particular invocation. | Note that local addresses are never passed to UUCP_MAILSHR. | | | 1.3.3.1.2 Continuation Lines In To: Headers - | | The handling of the To: header for inbound mail delivery has | been changed. Previously, UUCP_MAILSHR would pass to VAX Mail | just the first line of the header, ignoring any continuation | lines. Now, if the To: header is continued, as much of the | header as can be passed to VAX Mail will be. | | Note that this processing has nothing to with the delivery | address in the mail envelope. The contents of the To: header | are passed to VAX Mail so that it can construct the text for its | To: field which is used for displaying the message. WHAT'S NEW IN THIS RELEASE (1.3) Page 1-3 | The Mailer | 1.3.3.2 From: And From_ Headers | | 1.3.3.2.1 Generating VMSmail From: Lines From UUCP From_ Lines | If a received message contained a UUCP From_ but not an RFC 822 | From:, the UUCP From_ was ignored. This meant that for local | delivery, the VMS From: address was "(cannot determine sender)" | even though a valid address was in the message. This has been | fixed. | | | 1.3.3.2.2 Quoting Reserved Characters In Headers - | | RFC822 reserves certain characters for use in header text. | Literal instances of these character are supposed to be escaped | or quoted. For example, "." is a reserved character. A personal | name of the form "John Q. Citizen" contains the reserved "." in | a literal sense. Therefore, the "." must be quoted or escaped. | | Beginning with version 1.2a, the mail handler always produces the | entire personal name text in double quotes. Further, double | quote characters that appear in the text of the personal name are | escaped. Thus, a personal name of the form | | John Q. Citizen - "An honest guy, vote for me" | | will now appear as | | "John Q. Citizen - "An honest guy, vote for me"" | | in the "From:" header. | | | 1.3.3.2.3 UUCP From_ Lines For DECnet-origin Messages - | | A problem occured when DECnet was being used to submit mail to | UUCP. A user on a non-UUCP host, connected to a UUCP host via | DECnet, can give a "To:" address in the form | | HOST::UUCP%"user@domain" | | The "From" address delivered to the mail handler contains the | DECnet specification - HOST::Username. The [OUTBOUND-FROM] | rewrite can be used to convert "From" addresses in this form into | a correct Internet form. | | However, in version 1.2, the result of the rewrite only applied | to the RFC822 From: header. The UUCP From_ line ended up in the | form | | From host::username remote from uucphost | | This form is illegal. (This was actually fixed in 1.2a.) WHAT'S NEW IN THIS RELEASE (1.3) Page 1-4 | The Mailer | 1.3.3.2.4 Not Generating From: Headers - | | Version 1.2 introduced a feature which added missing headers to | messages which were passing through the local system from one | host to another. Among other problems, this feature would | generate an RFC 822 From: header regardless of whether or not a | UUCP From_ header was present. The generated From: contained an | address indicating that the message came from uucp_daemon on the | local host. | | The net effect was that downstream mailers might have ignored the | correct return address in the From_ header, instead using the | false one in the From: header. | | For this release, the mail handler no longer supplies missing | headers on pass through mail. | | | 1.3.3.2.5 From: Headers With No Personal Name - | | Some Unix hosts running MMDF were complaining about a "parse | error" when processing the "From:" generated by the mail handler. | The problem appears to have been caused when mail was sent from a | user that had not defined a personal name. | | A strict reading of RFC822 indicates that in the absence of a | personal name, the address should not be placed in "<>". This is | now handled correctly. | | (This was actually fixed in 1.2a) | | | 1.3.3.2.6 Processing Of Ugly From: Headers - | | A received message that contained a really ugly RFC 822 From: | header caused UUCP_MAILSHR to crash with an access violation. A | short scratch buffer was located in the bowels of the address | rewriter. The text of the From: was longer than the buffer | causing the stack to become trashed. The length of this scratch | buffer has been changed to exceed the length of the text passed | to the address rewriter. (This was actually fixed in 1.2a.) | | | 1.3.3.3 Other Headers | | 1.3.3.3.1 X-VMS-To - | | The generation of the X-VMS-To: header has been intermittent in | the past. Sometimes VAX Mail would pass the information and | sometimes it wouldn't. The reason for this has been found and | the problem has been fixed. WHAT'S NEW IN THIS RELEASE (1.3) Page 1-5 | The Mailer | 1.3.3.3.2 Message-ID - | | Version 1.2 introduced the processing of Message-Id headers. | RFC822 indentifies the header name as "Message-ID", but, in | practice, most of the Internet uses "Message-Id". (Lower case | "d".) | | The test for the header name was case sensitive. This caused the | code to miss valid "Message-Id"'s causing it to create another | one. The test has been changed to be case insensitive, also, for | conformity, the generated field name now uses the lower case "d". | | (This was actually fixed in 1.2a.) | | | 1.3.3.4 Crash Dump Facility | | A "crash dump" facility has been added to UUCP_MAILSHR. This | facility is normally dormant, it must be enabled before it takes | effect. | | When the "crash dump" facility is enabled, the signalling of any | unexpected conditions will cause a crash dump file to be written. | Expected conditions are those whose messages begin with a | Facility ID of "%UUCP". Anything else, such as an access | violation or a runtime library error, are considered unexpected | and will cause a crash dump file to be written -- if crash | dumping is enabled. | | To enable the crash dump facility: | | DEFINE UUCP_MAILSHR_CRASH_DUMP anything | | When a crash occurs, the file SYS$SCRATCH:UUCP_MAILSHR.CRASH_DUMP | will be created. This file should be included in any problem | reports. | | Note that the condition "%UUCP-F-NORECIP, Required recipient | parameter on command line missing" if often wrong and actually | indicates a condition that would generate a crash dump. | | | 1.3.3.5 File Handling | | 1.3.3.5.1 Always Closing PATHS - | | The Paths. file was not explicitly closed at the end of an | outgoing mail session. This never really caused a problem since | the exit from MAIL itself caused the file to be closed. | | However, people who use the DECwindows mail utility usually put | it in the icon state and only exit every few days. This could | cause out of date versions of the Paths. file to be used. WHAT'S NEW IN THIS RELEASE (1.3) Page 1-6 | The Mailer | UUCP_MAILSHR now closes the Paths. file explicitly during the | termination of a session with VAX Mail. | | | 1.3.3.5.2 Required Origin For Inbound Mail Files - | | During inbound mail delivery, UUCP_MAILSHR now requires the input | file to reside in UUCP_SPOOL:. This change should only affect | alternate mail transport systems such as Matt Madison's MX. | | | 1.3.3.5.3 "X" File Contents - | | The "U" line in "X" files contains the username and host which | produced the UUCP request. Some UUCP systems, such as | HoneyDanBer, use this information to determine which commands | UUXQT may process. | | Some implementations appear to choke on a username longer than 8 | characters. HDB as implemented under Xenix has been reported to | have this problem. | | Versions of the mail handler prior to 1.2 generated all manor of | interesting things for the "U" line. For 1.2, the behavior was | changed to always generate "U uucp_daemon yourhost". At 1.2a, | the mail handler was changed again to generate "U uucp yourhost" | in the X file. | | | 1.3.3.6 Miscellaneous Fixes | | 1.3.3.6.1 Compatibility With VAX PSI - | | Patches for VAX PSI version 4.3 broke the inbound delivery | interaction between UUCP_MAILSHR and VAX Mail. This problem has | been found and fixed. | | | 1.3.3.6.2 Logicals For Personal Name - | | Version 1.2 introduced a feature allowing UUCP mail users to | override their VAX Mail personal name. This is done by defining | either the NEWS_PERSONALNAME or UUCP_PERSONALNAME logical name. | The definition of the logical contains the personal name text to | be used. | | The search order for the two logical names was backwards. For | 1.2, the code looked for NEWS_PERSONALNAME, then if it was not | found, looked for UUCP_PERSONALNAME. Intially, this ordering | made sense. Under further reflection, it was seen that the order | was backwards. The current code looks for the logical | UUCP_PERSONALNAME; if that logical is not defined, it looks for | NEWS_PERSONALNAME; if that isn't defined either, the user's | VMSmail personal name is used. WHAT'S NEW IN THIS RELEASE (1.3) Page 1-7 | The Mailer | (This was actually fixed in 1.2a.) | | | 1.3.3.7 Miscellaneous Changes | | 1.3.3.7.1 Change From BISON To Yacc - | | BISON, the GNU Yacc-alike, is no longer supplied with DECUS UUCP. | We have changed to Berkeley Yacc, source for which is included in | this release. | | Since this is a development tool, the source code is in the | [.YACC] subdirectory of UUCP_TOOLS:. The executable is in | UUCP_TOOLS: | | | 1.3.3.7.2 Development Direcotory Structure Changes - | | The source code directory structure for the Mail Handler | components has been rearranged. This includes the source code | for UUCP_Mailshr, Pathalias, PathProc and Smail. Previously, | each of these components had their own subdirectories under | [UUCP.ORIG_CODE] and [UUCP.DEVEL]. | | The subdirectories have been pushed down one level, and are now | found in [UUCP.ORIG_CODE.MAIL_HANDLER] and | [UUCP.DEVEL.MAIL_HANDLER]. This rearrangement is in preparation | for some signficant Mail Handler component changes in a future | release of DECUS UUCP. CHAPTER 2 CONCEPTS AND TERMINOLOGY This chapter will attempt to provide background information for those unfamiliar with uucp networks in general or with DECUS uucp in particular. 2.1 The Basics In the Unix world, "uucp" means "Unix to Unix Copy". (We now prefer to think of it as "uucp to uucp copy".) This is the name for a set of programs which allow Unix systems to copy files to one another over (mostly) dialup telephone links. Several different link-level protocols, identified by single letters, are used; over dial-up links, the "g" protocol is most common. On Unix, "uucp" is also a command, available at the command line interpreter ("shell") prompt, for requesting such a file transfer. Unix also supplies a "uux" command, for "Unix to Unix execute". This command accepts a shell command as an argument and copies this command to a neighboring system via uucp. The shell command is then executed on the neighboring system. Uucp is used for mail transfer in the following manner: A user sends mail to an address of the form "othersite!user". Two files, a "data file" and an "execution file", are copied to the neighboring system "othersite". Upon receipt of the execution file, the "uuxqt" program on the neighbor system interprets the execution file. The execution file includes an "rmail" shell command which mails the data file to "user", the intended recipient. File transfer via uucp is limited to adjacent, or neighboring, systems, but mail can be sent to nonadjacent sites via "bang path" notation. (So called because, when such addresses are read aloud, the exclamation point is pronounced as "bang".) For example, if my node talks to a node called "ibm", and "ibm" in turn talks to "dec", and I have a friend who uses "dec" with the username "ken", I can send mail to ibm!dec!ken . In this case the rmail program at ibm sees a "to" address of "dec!ken", and queues the mail back into the uucp system, exactly as if it had been sent to dec!ken from someone on ibm. When it arrives in CONCEPTS AND TERMINOLOGY Page 2-2 The Basics ken's mailbox the "from" address says dec!ibm!myname -- each system prepends its own name to the "from" address as the mail passes through -- so that replies work. News is handled in a similar fashion, with data and execution files, although the routing mechanism is different. In general, each site sends news items to all adjacent sites through which the items have not yet passed (as determined by a "path" header which is constructed on each item). There are many redundancies and other potential sources of "loops" in the news distribution routes, so that a given site might receive the same news item from several sites, but this is taken care of by putting a unique identifier on each message when it is created; no machine will keep more than one copy of a message with a given identifier. 2.2 What Is DECUS UUCP? DECUS uucp is a partial implementation of uucp facilities for VMS systems. It provides support for uucp mail and news transfer, allowing you to join the existing uucp mail and news network. User-requested file transfers (the "uucp" command) are also available, but at present files can only be received into uucp's spool directory, and by default, the DECUS uucp system will not respond other systems' requests to receive files. There is no provision for user-requested remote command execution (ie, no "uux" command is provided). At the heart of DECUS uucp is the program "uucico" which, like Unix's uucico, performs the actual file transfer from one machine to another using the "g" protocol. About twenty other executable programs and command procedures provide "uuxqt", interfaces to mail and news, and various support functions. 2.3 How Do I Apply To Join The Network? You don't; the uucp network has no central authority. You join the network by finding one or more (hopefully) nearby sites with whom your uucp machine will exchange phone calls. Information provided with DECUS uucp (in this document and elsewhere) will help you find such a site. There are two optional steps you can take to make it easier for other sites to send mail to you. First, you are strongly encouraged to publish your "uucp map entry". This is a description of your uucp connections (sites you exchange phone calls with) in a well-defined format. "Publishing" it consists of mailing it to a special mailbox at rutgers, making it available to the "UUCP Mapping Project" (all volunteers). Soon it appears in a special newsgroup in the network news and is used, automatically, to update each uucp host's routing tables. The result of all that is that uucp sites running "smart mailers" (which includes DECUS uucp sites) can simply send mail to alan@frisbie (or whatever), without worrying about how the mail will get there. CONCEPTS AND TERMINOLOGY Page 2-3 How Do I Apply To Join The Network? Going one step farther, you can register all the machines you control as an "Internet domain". This makes it easy for people on the Internet to send mail to you, again without having to find an Internet/uucp gateway. It also makes it possible for you to allow other machines on your company's internal network to send and receive uucp mail, without your having to publish map entries for them all. Details on uucp maps and Internet domain registry are in subsequent chapters. 2.4 How Are Mail And News Supported? Under DECUS uucp, VMS users send and receive uucp mail with the standard VMS Mail program. To send mail to someone via uucp, a special form of "To:" address is used. This function is provided via Mail's (undocumented) foreign mail protocol interface. Mail received via uucp appears to have come from addresses of the same form, so that Mail's REPLY command usually works correctly. For news, DECUS uucp includes command procedures and programs for integration with Geoff Huston's NEWS program (commonly referred to as "ANU News", for Australia National University, where Geoff works); we will either use this term, or spell NEWS in all caps, when confusion between the program and news in general would otherwise be likely). NEWS provides the user interface and implements the news database, and calls upon uucp for transfer of news items to and from remote sites. (NEWS can also transfer news items via DECnet and several other mechanisms.) 2.5 Netnews, Usenet, And VMSnet In the Unix world, "Netnews" is a coinage used to refer to the "Network news" in general. "Usenet" (User's Network) refers to the machines which carry news, or, more rigorously, to the machines which carry the newsgroups approved by the "Usenet backbone" sites. Note that this is not the same as "the uucp mail network", which refers to the machines which use uucp to exchange mail. For one thing, a lot of news is carried via means other than uucp; for another, many uucp links do not carry news, but only mail. Many people, however, mistakenly say "Usenet" when they should be saying "the uucp network", or just "the net". (Occasionally the distinction is important, but not usually.) Analogously, we have coined the term "VMSnet" to refer to sites running this software and exchanging the newsgroups in the "VMSnet hierarchy". More information on this is in the chapters on News integration. (We previously referred to the software itself as "the VMSnet software", but later realized that when people went looking for "uucp for VMS" in the DECUS Program Library catalog they wouldn't be likely to trip over "VMSnet".) CONCEPTS AND TERMINOLOGY Page 2-4 Internet... 2.6 Internet... "The Internet" is a conglomeration of machines talking to one another over hardwired point-to-point links, LANs, leased lines, packet-switching networks, and so on, using TCP/IP protocols. They share a common node address space, and addresses are coordinated and registered with a central authority, the Network Information Center at SRI in Menlo Park, California. Internet includes what used to be called Arpanet, that part of the Arpanet which is now called Milnet, and many others. For administrative purposes, the Internet is divided into hierarchies called "domains". (The "administrative" distinction ___ is important. Domains do not, in general, reflect connectivity.) There is a "top-level" domain for each foreign country, with the domain name derived from the ISO country name code. Within the United States there are several top-level domains with names like ".com" (commercial institutions), ".edu" (educational), and ".mil" (military). A typical system name within the Internet is arisia.dnet.ge.com and a typical mail address is everhart@arisia.dnet.ge.com where "ge" is a company name and "arisia.dnet" identifies a machine at ge. [1] A uucp connection does not provide "a connection to the ________ Internet". However, there are numerous uucp/Internet gateways -- machines which are connected to Internet and which also can send and receive mail via uucp, and which can forward mail between the two. If you can get an Internet site to agree to act as your mail forwarder (this is usually quite easy), you can register your site in the domain system; Internet sites will then be able to easily send you mail. [2] Thus, a uucp connection is sufficient to get an "Internet address" for your site and for everyone reachable through your site, though technically you won't be "an Internet site". The chapter on "Internet Registry" provides more information. The mail routing software used on Unix systems, and ported to VMS as part of DECUS uucp, supports the Internet addressing syntax, and also allows systems that are not registered with the Internet -- but which are listed in the uucp maps -- to be ____________________ [1] Yes, this is Glenn Everhart, VAX SIG Tapecopy coordinator and member of the DECUS Library Committee. ____________________ [2] They can send you mail even if you haven't registered and arranged for a specific forwarder, by explicitly routing their mail to you through one of the better-known gateways. But ____ registering your site makes it much easier for them. CONCEPTS AND TERMINOLOGY Page 2-5 Internet... addressed via "Internet-style" names. 2.7 ...And Beyond Collectively, the uucp mail network, the Internet, and the many other networks (SPAN, Bitnet, HEPNET, Digital's Easynet, and others) that are gatewayed into Internet, form a worldwide ___________ metanetwork, which for convenience is most often called "the net". An excellent (now dated, but still excellent) source of information about "the net" is the article "Notable Computer ______________ __ ___ ___ Networks" by Quarterman and Hoskins (Communications of the ACM, Volume 29, Number 10 (October, 1986), pages 932 through 971). ___ _______ A much-expanded version of this material appears in The Matrix: ________ ________ ___ ____________ _______ _________ Computer Networks and Conferencing Systems Worldwide by John S. Quarterman, published by Digital Press. (Order number EY-C176E-DP; $59.95 plus tax. Digital Press, DEC, 12 Crosby Drive BU0/E94, Bedford MA 01730 U.S.A. We highly recommend this book.) CHAPTER 3 INSTALLING THE FILES The files here should restore into [VAXxxx.UUCP...] if you have received this from a VAX SIG tape, or into [UUCP...] if you receive this distribution directly from the authors or from the DECUS Library. For all future references to the directories, we will assume that [UUCP] is a top-level directory and that device:[UUCP] is the default. For example, [UUCP.BIN] will be referred to as [.BIN]. This directory tree is a copy of the "live" tree in use at Simpact (minus, of course, our current news data base, log files, and sensitive information such as our neighbor systems' phone numbers, usernames, and passwords). The intent is that you can restore the tree from the tape, edit some configuration files to match your site's requirements, define a few logical names to point to the disk containing the ufd [UUCP], and everything should work. You can change it all around if you like, but we haven't designed things with this in mind and have done no testing with any other tree structure. In particular, though we have tried to use a separate logical name for each directory used at run-time, there may be a few assumptions lurking in the code about what directories are subdirectories of other directories; so if you do decide to reorganize things, be prepared to chase down some problems. | | | 3.1 "Example" Configuration Files And Command Procedures | | There are several text files and command procedures which you | need to edit to set things up for your particular environment. | Full details on this appear later, but for now we need to mention | the location of the example files. | | There is a subdirectory tree, [.EXAMPLES...], which contains | "examples" or "templates" for each such file. For example, one | file that uucp needs is called [.CFG]SYSTEMS. You won't find a | file called [.CFG]SYSTEMS. here, but you will find one in | [.EXAMPLES.CFG]SYSTEMS. You'll need to edit the latter to create | the former, according to instructions given in a folowing | chapter. INSTALLING THE FILES Page 3-2 | "Example" Configuration Files And Command Procedures | The intent of this scheme is twofold: First, you never have to | worry about doing a PURGE and losing the original versions of any | of these files; and second, you can install this package on top | of an existing earlier version of DECUS uucp without having your | "live" files supplanted by our examples. | | You should of course not assume that you need make no changes in | your existing configuration files; review the new examples, and | the documentation here for each, to see what's changed. The | right thing to do in most cases will be to edit the new example | file to create your new live file, using your old live file as a | guide. | | Where we have referred to these "to be edited" files in the | documentation, most references will be to their "live" locations, | e.g. [.CFG]CONTROL. rather than [.EXAMPLES.CFG]CONTROL., even if | we haven't gotten to the place in the procedures where we create | the live file yet. 3.2 Space Requirements | The total space required for these files is about 40,000 blocks. | | 23,000 blocks of this are a compressed BACKUP saveset, | [UUCP]DEVEL.BKP-Z, which contains source files, object files, and | development tools; if you have no plans to work on the software, | you don't need to restore this to disk. Use a qualifier such as | /EXCLUDE=DEVEL.BKP-Z on your backup command. The total space | requirement will then only be about 17,000 blocks. | | If you do want the files from DEVEL.BKP-Z, use the tools | "compress" and "modatt" in this package to restore it: | | o Restore to disk at least the [UUCP.BIN] directory and | [UUCP]DEVEL.BKP-Z . | | o Define the logical name UUCP_BIN to point to the device | and directory ddcu:[UUCP.BIN] . | | o Invoke the command procedure @UUCP_BIN:USERCMDS . This | defines various foreign commands for the uucp system and | associated utilities. | | o Invoke the compress utility to decompress the saveset: | | $ compress -d devel.bkp | | This may take up to half an hour or so, depending on the | speed of your CPU and your disk. The decompressed | saveset will take about 43,000 blocks. compress will | automatically delete the compressed version when it's | finished, but until then you'll of course need enough | room on the disk for both the compressed and | decompressed versions (63,000 blocks total). INSTALLING THE FILES Page 3-3 Space Requirements | o Define and use the MODATT command to set the file | attributes of the decompressed saveset: | | $ modatt | | $ @devel.att | | o Use BACKUP to restore the contents of the saveset to | disk: | | $ BACKUP devel.bkp/save [*...] | | The files inside the saveset will total about 40,000 blocks. | They can be restored to another disk, or you can copy the saveset | to tape, delete it from disk, and then restore it from the tape. | | | 3.3 ANU NEWS | | The current (as of this writing) version of Geoff Huston's ANU | NEWS is V6.0-2. It appears here in [.NEWS60]. NEWS has its own | documentation in [.NEWS60.NEWS_DOC]; we provide additional setup | instructions in later chapters in this manual. CHAPTER 4 MODEMS AND MULTIPLEXERS This chapter describes how to set up modems and serial lines for connections to uucp neighbors. A great deal of this information is also applicable to modems and serial lines used for ordinary interactive dialin, so if you are having problems with that, keep reading. (If interactive dialin doesn't work, uucp dialin won't work either, though uucp dialout might.) NOTE The following sections will discuss the need to change some of the terminal-related SYSGEN parameters. The needs for another SYSGEN parameter change will be described in a later chapter. Hold off on all parameter changes until then. 4.1 Setting Terminal Characteristics The serial ports you'll use for uucp dialin and dialout may be configured in such a way that they are useful for ordinary interactive dialins as well as for uucp. 4.1.1 Conventional Multiplexers The port should at least support what DEC calls "partial modem control". (A later section on RS232 control signals describes the requirements in detail.) For a conventional serial port (that is, not one that comes out of a terminal server), all that is necessary is to an issue an appropriate SET TERMINAL command: | $ SET TERMINAL TXA1: /PERMANENT /AUTOBAUD /SET_SPEED - | /MODEM /DIALUP /HANGUP /DMA /NOPARITY - | /TYPEAHEAD /ALTYPEAHD - | /SYSPASSWORD /DISCONNECT - | /HOSTSYNC /TTSYNC /LINE_EDIT /DEVICE=VT100 | | The qualifiers on the first three lines are required (with MODEMS AND MULTIPLEXERS Page 4-2 Setting Terminal Characteristics | possible modifications as described below). | | If your modem is one (such as a Telebit) that can use a single | locked host interface speed while making connections at various | (lower) speeds, use /SPEED=nnnn/NOSET_SPEED instead of | /AUTOBAUD/SET_SPEED . Syspassword can be used as you deem appropriate; uucp systems (including ours) are able to negotiate logins involving system passwords, so if you normally use system passwords for dialin lines there is no reason not to use them for uucp. The other qualifiers on the last two lines are for the benefit of interactive users who dial in through the same line used by uucp. Uucp changes these as appropriate (in particular, it turns off hostsync, ttsync, tab, etc., and sets pasthru), and changes them back at the end of each call. Along with enabling the alternate typeahead buffer on the lines to be used by uucp, we recommend that you raise the SYSGEN parameter TTY_ALTYPAHD from its default of 200 bytes to 210 bytes. (This is not a dynamic parameter, so a reboot is necessary for the change to take effect.) Together with the /ALTYPEAHEAD characteristic, this will allow the remote system to send you a complete "window" of three uucp data packets (70 bytes each, including 6-byte headers) without overrunning the typeahead buffer, even if you can't get around to posting any reads for a while. This parameter change will have an utterly trivial effect on nonpaged pool usage (ten extra bytes will be allocated for each port set to /ALTYPEAHD). If you don't make this change, and some characters are dropped in this fashion during a uucp transfer, the receiving system will simply ask the sending system to send the corrupted packet(s) again. No data will be lost, but throughput will suffer. | | | 4.1.2 LAT Ports | | DECUS uucp will work with modems on DECserver200 MC (Modem | Control) ports, provided that: | | o The DECserver is running V3.0 (or later) of the DS200 | software. (Earlier versions do not allow the VAX enough | control over the port.) | | o The modem is configured to send call progress result | codes, in particular a success indication such as | "CONNECT", to the local DTE, when making an outgoing | call. (Hayes-like modems will do this.) This is | desirable for all modems but absolutely essential for | modems on LAT ports, since the VAX has no way to read | the carrier detect signal from a LAT port. (The modem | must still provide a proper carrier detect signal for | the benefit of the DECserver itself.) MODEMS AND MULTIPLEXERS Page 4-3 Setting Terminal Characteristics | Let's suppose you are setting up port 2 on a DECserver whose node | name is "DSRV01". We are assuming that the port's name has not | been changed (in the server) from its default of PORT_3. | | Issue the following commands: | | $ RUN SYS$SYSTEM:LATCP | CREATE PORT LTA1200: /NOLOG | SET PORT LTA1200: /APPLICATION /NODE=DSRV01 /PORT=PORT_3 | EXIT | | (When you are confident that everything is working, place these | CREATE and SET PORT commands in your LTLOAD.COM.) | | Now, tell the terminal server to configure the port as follows | (Only changes from the default settings are listed): | | ACCESS DYNAMIC DSRLOGOUT ENABLED | DIALUP ENABLED LOSS NOTIFICATION DISABLED | DTRWAIT ENABLED MODEM CONTROL ENABLED | | plus your choice of either | | AUTOBAUD ENABLED and REMOTE MODIFICATION ENABLED (A) | | or | | AUTOBAUD DISABLED and SPEED nnnn (B) | | If your modem's host interface speed "floats" according to the | speed of the connection, use option (A). If your modem supports | a locked host interface speed regardless of actual connection | speed, you can use option (B). If the modem will operate either | way, our preference is to avoid autobaud hassles and go with | locked interface speeds, but your experience may be different. | Either way, be sure to configure the modem appropriately. | | Here is the complete "LIST PORT" output from the port. This is | from an actual DECserver 200MC port that was successfully tested | with DECUS uucp. (In this case we are using a locked interface | speed.) | | Port 3: Server: DSRV01 | | Character Size: 8 Input Speed: 19200 | Flow Control: XON Output Speed: 19200 | Parity: None Modem Control: Enabled | | Access: Dynamic Local Switch: None | Backwards Switch: None Name: PORT_3 | Break: Local Session Limit: 4 | Forwards Switch: None Type: Soft | | Preferred Service: None | | Authorized Groups: 0 MODEMS AND MULTIPLEXERS Page 4-4 Setting Terminal Characteristics | (Current) Groups: 0 | | Enabled Characteristics: | | Autoprompt, Broadcast, Dialup, DSRlogout, DTRwait, Input | Flow Control, Message Codes, Output Flow Control, Verification | | In the following section on RS232 control signals, we mention the | desirability of using CTS flow control with certain types of | modems. We have found that the DECserver 200MC ports honor CTS | flow control even when set to the default of XON flow control. | Since XON flow control is useful if interactive users will be | dialing in through the modem, it is a good idea to leave it ___ | enabled. DECUS uucp tells the port not to use XON/XOFF flow | control while the the uucp protocol is running. | | Most uucps (including ours) have sufficient scripting ability to | be able to log in to the server port, CONNECT to the appropriate | service, and then log into the VAX. You can of course use server | options like AUTOCONNECT ENABLED, BREAK DISABLED, DEDICATED | SERVICE, and USERNAME to simplify the connection process for | incoming uucp calls. This of course may reduce the usefulness of | the port and modem for normal interactive logins. | | As described in the preceding section on non-LAT ports, uucp | needs a typeahead buffer of (at least) 210 bytes. Enabling this | on LAT ports presents a special problem. | | We can issue a SET TERMINAL /PERMANENT/ALTYPEAHEAD command on the | port we've created for outbound calls (LTA1200: in the preceding | example), but this doesn't help for incoming calls, as a new | LTAnnnn device is created for each login -- and the alternate | typeahead characteristic can't be enabled afterwards. Instead it | must be specified by setting bit 7 (hex 00000080) in the | system-wide default terminal characteristics mask given by the | SYSGEN parameter TTY_DEFCHAR. | ___ | This enables the alternate typeahead buffer for all terminals, | and this in turn suggests an easier solution: Leave TTY_DEFCHAR ________ | alone, and simply set the standard typeahead buffer size | (TTY_TYPAHDSZ to 210. The cost in nonpaged pool space will be | about 130 extra bytes per terminal device. 4.2 Data Path Requirements For simple situations, where you and your network neighbors have standard modems and phone lines and you call each other, data path requirements are (probably) taken care of, and you can skip this section. (But you should probably read it anyway, just to make sure that everything is ok.) Often it is desirable to run uucp over more complex connections that just happen to look like serial links at each end. A typical example is a packet-switching network providing X.29 PAD service; you might have your VAX dial a local PAD, then connect MODEMS AND MULTIPLEXERS Page 4-5 Data Path Requirements through the network to the target system. This section describes the pitfalls that may be encountered in such environments. Uucp must do all serial line I/O in what Unix calls "raw" mode, requiring an eight-bit-wide, fully-transparent data path. This means that all 256 possible eight-bit characters, from NUL (with high bit clear) to DELETE (with high bit set), must be transferred without deletion or modification by any part of the link. Even if you will only be sending mail and uncompressed news (in other words, plain Ascii text files), "funny characters", which might literally be any characters out of the possible 256, often appear in the packet headers. So, no part of the serial link may change the high bit of each character to a parity bit, or clear it, or set it, or do anything else to it other than send it intact. Furthermore, no element of the serial link may add any characters to those sent or received, or assign any significance to any characters or sequence of characters. This precludes the use of "inband" flow control (e.g. XON/XOFF, ENQ/ACK, etc.). Flow control is not required anyway (except with special modem types; see below), since uucp's link-level protocol has its own flow control mechanisms built in. Many connections over packet-switching networks will violate these rules (by setting the high bit of each byte to be a parity bit, interpreting "@" characters as PAD commands unless sent twice, and so on) unless special steps are taken when setting up a call. On the other hand, we are told that Telenet's PC Pursuit (tm) works fine (we haven't tried it). NOTE The following sections give detailed requirements for modems, serial ports, and cables to be used for DECUS uucp dialout and dialin. If you already have some modems that are working on your VAX ports, they will probably work as-is; you can probably skip ahead to the "Testing" and "Summary" sections at the end of the chapter. Most of these considerations are not specific to DECUS uucp; they apply equally to modems and ports used for interactive dialin and dialout. 4.3 Requirements For Serial Ports ("Can I connect a modem to this port?") At a minimum, a serial line to be used with uucp (or for ordinary dialin applications, for that matter) must supply a Data Terminal Ready (DTR) signal and must interpret Carrier Detect (CD). ___ Multiplexers that we know do not meet this requirement include the CXA16, ports 2 through 7 of the DMF32, the serial port on (at MODEMS AND MULTIPLEXERS Page 4-6 Requirements For Serial Ports least early models of) the VAXstation 3100, and those ports on the MicroVAX 2000 which are implemented through modified modular jacks (MMJs). The VAX normally keeps DTR raised, but it is dropped momentarily in response to $QIO requests (which uucico issues at appropriate times, such as at the end of a call), when the assigned channel count for the terminal goes from nonzero to zero, and when VMS detects exceptions in the expected sequence of modem control signal transitions. A terminal multiplexer which keeps DTR raised at all times, or which "pretends" that CD is raised at all ___ times, can not be used with uucp. NOTE You can break the above rules and use a non-modem control port, provided that you don't allow inbound calls, and provided that the modem has some way, other than dropping DTR, for the VAX to get its attention and make it hang up the line. The restriction on inbound calls is for security: If someone calls in and disconnects without logging out, the VAX is supposed to force the modem to hang up, and the only way it knows how to do this is by dropping DTR. (DECUS uucp can use other means, but VMS can't for an ordinary interactive dialin call.) If the VAX cannot do this, the next caller will land in the previous caller's process without having to log in. A later section goes into more detail on RS232 control signals. 4.4 Requirements For Modems 4.4.1 Buffering The modem must not do any buffering of data when uucp is running. In particular, this means that MNP and similar schemes must be disabled during uucp calls. (The sole exception is the Telebit PEP mode when doing uucp spoofing.) 4.4.2 Result Codes To properly accept incoming calls, modems must not send "result codes" to the "local DTE" (that is, to your VAX) when incoming calls are being placed. MODEMS AND MULTIPLEXERS Page 4-7 Requirements For Modems 4.4.2.1 Background When you are dialing out through a modem, the modem usually sends you result codes (such as "OK", "RINGING", "CONNECTED", etc.) to inform you of the progress of the call. This is fine, and uucp's dial scripts use these result codes (if visible) to keep things in step. However, many modems also send similar codes to the VAX for ________ incoming calls. For example, Hayes-type modems send the word "RINGING" when the ring signal for an incoming call appears, followed by "CONNECT". 4.4.2.2 The Problem The trouble is that at this point no one has a channel assigned to the serial port in question, and VMS responds to these codes as it would to any other unsolicited input: It starts a login sequence. This means that it sends a "Username:" prompt, or perhaps (if system passwords are enabled) just a bell, to the ____ ___ modem. And the Hayes-type modems we have tested will drop the __________ connection if they get data on their serial port (that is, from the local VAX) in the interval between detection of an incoming call and the establishing of carrier between the two modems. The establishing of carrier does not occur for some time, often several seconds, after the "RINGING" message is sent to the VAX. The result of all this -- and the tell-tale symptom of this problem -- is that the modem will answer the phone and send carrier back to the modem that originated the call, but before the other system (or user) can log in, the call is dropped and the remote system sees the carrier go away (assuming that there was time to establish carrier at all). So the modem will be useless for incoming calls, though outgoing ones will likely work fine. (Colloquially, this is known as the "chatty modem" syndrome.) 4.4.2.3 Solutions Some modems can be optioned to turn off result codes for incoming calls, but to automatically enable them for outgoing. This is an ideal solution; owners of such modems can configure them this way, (hopefully) store the settings in the modem's nonvolatile memory (so they persist through power off/on cycles), and skip the rest of this section. A majority of Hayes-type modems have an option to turn off result codes entirely. This is less desirable; we'd like to see result codes on outgoing calls. Without them we have to dial the modem "blind", [1] the only way we have to detect call success is watching for Carrier Detect (CD) to be raised after we send the whole dial sequence to the modem, and we can only detect dial failures via a timeout while waiting for CD. MODEMS AND MULTIPLEXERS Page 4-8 Requirements For Modems DECUS uucp addresses this through its "dial scripts". You configure the modem to suppress result codes completely, so it works fine for incoming calls. For outgoing calls the dial script tells the modem to turn result codes on as the first step in the dial sequence. A corresponding "hangup script", executed after each call, turns them back off again. There is a small window of vulnerability -- if uucico dies before it has run the hangup script, the modem will be left with result codes enabled, and will be unable to accept calls. Uucico's death is most often due to unexpected system shutdowns and the like (we have never seen this version simply exit with an access violation or other exception), and we have not yet written the kernel mode image rundown handler necessary to deal with this situation. For now, if uucp has been stopped in the midst of an outgoing call, you will have to reset the modem it was using manually. (Or just wait until it places another call and ____ completes it. It doesn't matter whether the call completes successfully; that is, uucp will still run the hangup script after, for instance, a call is aborted due to a busy signal.) Some modems have a nonvolatile memory in which user-specified configuration parameters (different from the factory's) are stored, and will reset to these parameters whenever the Data Terminal Ready (DTR) signal from the VAX is dropped. This is a good feature, as it eliminates the "window of vulnerability". You set up the modem to not send result codes and store this setting in the modem's memory. The dial script temporarily turns _____ result codes on. Since every call ends with DTR being dropped (even if someone does a STOP/ID=nnn on uucico's process), the modem will always be reset properly. (See the discussion of DTR in a later section.) 4.4.2.4 Special Considerations For DMF32 Users If the modem in question is attached to port 0 or 1 of a DMF32, _______ ___ _____ there is no problem, because the DMF32 ignores all input from the serial port until the modem (or whatever is attached) raises Carrier Detect (CD). The ignored data is not even stored in the DMF32's hardware buffers, it is utterly ignored. Of course, once CD is raised, it is perfectly safe for the VAX to send a Username: prompt to the modem. The bad aspect of this is that the dial procedure has to operate blind, since it can't see result codes. (The script language has a way to detect "blind" multiplexers -- at present, the DMF32 -- so that scripts need not expect result codes when none will be forthcoming.) ____________________ [1] Modem manufacturers use the term "blind dialing" to refer to dialing without waiting for a dial tone. We use it to refer to dialing without being able see the modem's response codes. Sorry about that. MODEMS AND MULTIPLEXERS Page 4-9 Requirements For Modems A few modems, such as some models made by Racal-Vadic, can be optioned to use Carrier Detect normally for incoming calls, but to raise it immediately for outgoing calls (that is, as soon as the modem detects the start of the dial command sequence). Once carrier is received from the other end, CD assumes its normal role -- that is, if carrier is lost, the modem will drop the CD signal, even during an outgoing call. If available on your modem, this option provides a good solution to the "DMF32 problem". If your modem acts this way, you'll have to make sure that your dial script (described in later chapters) ignores the carrier signal from the modem, relying solely on the modem's result codes to determine when an outbound call succeeds. 4.5 RS232 Control Signals VMS places stringent requirements on how the modem and the VAX port use RS232 control signals, particularly for incoming calls. Uucp adds a few more requirements. In general, if you can use the modem and port for incoming calls, it is probably set up properly for uucp; but there are a few exceptions to this, as described below. 4.5.1 Data Terminal Ready (DTR) The VAX must be able to drop DTR at the end of a call, and the modem must hang up the line when the VAX drops DTR. Many modems have a switch or setup option to "force DTR high" (which really means "ignore DTR and assume that it's high", since DTR is controlled by the local VAX, not the modem); this must be disabled so that the modem always obeys DTR as signalled by the VAX. 4.5.2 Carrier Detect (CD) On inbound calls, the modem should raise CD when, and only when, a carrier is received from the remote modem. If carrier is absent, CD must be low (false). Many modems have an option to force Carrier Detect high, even in the absence of a carrier from a remote modem. This option must be disabled; CD must accurately reflect the presence or absence of carrier. | | Some modems can be set up to use CD correctly for inbound calls, | but to raise CD immediately for outbound calls, as soon as | commands from the local system are recognized. If your modem | acts this way, you'll have to make sure that your dial script | (described in later chapters) ignores the carrier signal from the | modem, relying solely on the modem's result codes to determine | when an outbound call succeeds. MODEMS AND MULTIPLEXERS Page 4-10 RS232 Control Signals 4.5.3 Data Set Ready (DSR) Some modems always raise DSR when they are ready to receive data (such as dialing commands) from the local system; others can be optioned to do so. Modems to be used with VMS cannot use DSR in this fashion. 4.5.3.1 DSR And Local Multiplexers Whenever VMS sees DSR raised, it enters a thirty second wait; if the modem has not raised CD and Clear To Send (CTS) by the end of the wait, VMS will drop DTR to the modem, forcing a hangup. [2] The symptom of this is that the "DTR" light on the modem will turn off for two seconds, every thirty seconds, when the modem is not in use. If you see this happening, your modem is asserting DSR continuously, and you must correct this. This makes outward dialing difficult, since it often takes longer than thirty seconds for carrier to be received. | | | 4.5.3.2 DSR And Terminal Servers | | The DECserver 200MC will not relay characters from the modem to | the VAX if DSR is raised in the absence of CD. If the modem | keeps DSR raised all the time, or if it raises it in response to | an "attention" command (such as "AT" for Hayes-type modems), the | VAX will be unable to see result codes from the modem. This will | make it impossible for the uucp software to recognize when a call | has been successfully placed to a remote modem. 4.5.3.3 Arranging For Correct DSR Signals The modem should be optioned so that DSR follows CD. If this is not possible, the problem can be solved with an adapter cable or breakout box. Disconnect the line connecting pin 6 (DSR) from the modem to the VAX, and jumper pin 6 to pin 8 (CD) at the VAX side of the cable, so that DSR follows CD as far as the VAX is concerned. (This of course assumes that the modem controls CD properly!) The following diagram should make this clear: standard wiring of DSR and CD: To modem To VAX port ____________________ [2] This is the "timeout" exit from the "Init" state in ___ ______ Figure 8-1 of the Terminal Driver chapter of the I/O User's _________ ______ Reference Manual. This behavior can be overridden by the TTY_DIALTYPE SYSGEN parameter, but this is not recommended. MODEMS AND MULTIPLEXERS Page 4-11 RS232 Control Signals DSR (6) >--------------------> (6) DSR CD (8) >--------------------> (8) CD modified to correct for "DSR always on" problem: To modem To VAX port DSR (6) >--------------x +--> (6) DSR | CD (8) >-----------------+--> (8) CD 4.5.4 Clear To Send (CTS) If the modem's host interface speed may be faster than the ___ | connection speed (as is true for Telebit modems), and it is to be | used by interactive users, the serial port on the VAX needs to support CTS flow control, and the modem must be set up to use it. That is, the modem must drop CTS when its buffer for outgoing data is getting full, and raise CTS when the buffer is emptied. The VAX (or DECserver port) must stop sending data when it CTS is dropped, and resume sending when the modem raises CTS again. This is not needed for "ordinary" modems, since pairs of such modems behave essentially like a long piece of wire. But if the modems provide buffering, data compression, error correction, data rate conversion, etc., the modem will on occasion need to tell the VAX to stop sending data for a moment. | | Flow control isn't needed during uucp connections because the | protocol provides its own. (This assumes that the modem's buffer | for outgoing data can hold at least 210 bytes.) XON-XOFF flow control between the modem and the VAX is not usable as it violates the "transparent data path" requirement. VMS supports CTS flow control with certain terminal multiplexers (those listed in the Terminal Driver chapter of the I/O User's Reference Manual, Table 8-1, as providing "full modem control"), [3] and with the ports on the DECserver 200MC. 4.5.5 Flow Control From VAX To Modem The VAX hardware and software do not provide any hardware flow control in the other direction; that is, the VAX has no way, other than XON/XOFF (which can't be used with uucp, so our software turns it off during uucp calls), to tell the modem "I'm busy, stop sending for a moment". Again, this is not generally a problem, since uucp has its own flow control in its packet-level protocol. MODEMS AND MULTIPLEXERS Page 4-12 RS232 Control Signals Special considerations apply for Telebit modems (again, see the relevant Appendix). Some modems (including the Telebits) can be optioned to use the Request To Send (RTS) signal from the local computer as a sort of reverse equivalent to CTS. This is a nonstandard use of RTS, but has become somewhat common in the personal computer world. It will not work with the VAX, since the VAX does not use RTS in this manner. Setups which would require the use of RTS flow control will therefore not work with VMS. (If your modem __ supports this option, it is safe to leave it enabled, but it won't accomplish anything.) 4.5.6 Sysgen Parameter TTY_DIALTYPE Set the three low-order bits of this parameter to 0 unless you have certain knowledge that something else is required. 4.5.7 Cabling The cable used to connect the modem to the VAX multiplexer must be a "straight through" and not a "null modem" type. At a minimum, this cable must connect pins 1 through 8, 20, and 22. As noted previously under the discussion of the Data Set Ready (DSR) signal, you may need to modify this if the modem insists on asserting DSR all the time. 4.6 Testing When you are finished, do the following if you have set up any new modems, or if you have never used dialout through your modems. Obtain another (compatible) modem, attach it to a terminal and phone line, and use it to call each of the new modems in turn. Make sure you can log in, do a few simple operations, and log out. If you can do this, remote uucp systems will (once you've configured the uucp system, as described in subsequent chapters) ____________________ [3] We have also tested the DB25 serial port connector on the MicroVAX 2000 (TTA2: if you have the three-port expansion box), and found that it also supports CTS flow control, though it is not listed as a "full modem control" device in the VMS documentation. CTS flow control has other uses. For instance, many third-party serial printers drop DTR to indicate "my buffer is full, send me no more data". Accessory "black boxes" are sold which convert this to XON/XOFF flow control, but the printer can be used as-is if the terminal line used supports CTS flow control and if a special null modem cable which connects the printer's DTR (pin 20) to the VAX's CTS (pin 5) is used between the printer and VAX. MODEMS AND MULTIPLEXERS Page 4-13 Testing be able to log in too. Then go back to a terminal on the VAX and do the following. (We assume that the modem being tested is attached to device TXA7.) $ ALLOCATE TXA7 $ SET TERM TXA7/SPEED=nnnn $ SET HOST/DTE TXA7 You will now be "talking to" the VAX's modem, and it will talk back (unless it's on a DMF32). Using the modem's manual, figure out how to send it a dial command, and tell it to dial the phone number of the modem from which you just called the VAX. The other modem should answer, and after that, characters which you type at the VAX terminal should appear on the screen of the "remote" terminal (but will not be echoed back to you), and vice versa. Type a control-backslash (^\) to disconnect, and then $ DEALLOCATE TXA7 4.7 Summary Here is a brief list of the requirements for uucp serial links. o Configure the VAX ports as you would for interactive dialins, but be sure to allow 210-byte typeahead buffers and, if the terminal multiplexer supports it, /DMA. o Ensure that the modem and other elements of the link from your system to your network neighbors will provide a fully-transparent, eight-bit-wide data path. o Configure the modem to not send result codes, or configure it to send result codes only for outgoing calls, or otherwise head off the "chatty modem" problem. o Ensure that your terminal port and modem correctly provide and interpret all of the required RS232 control signals. The most frequent pitfall here is a modem that constantly asserts Data Set Ready (DSR). o Use a straight-through cable that connects at least pins 1 through 8, 20, and 22, unless the modem asserts DSR at inappropriate times, in which case a modified cable may be used. (See the discussion of the Data Set Ready signal.) o Test the modem with simple dialin and dialout operations. o If you are using a Telebit modem, refer to the relevant Appendix for setup instructions. CHAPTER 5 ARRANGING FOR UUCP CONNECTIONS This chapter describes three "administrative" tasks which must be performed before you can begin configuring DECUS uucp. 5.1 Choose Your Host Name You must choose a name by which the network will know your site. We will refer to this as your "uucp host name", or just the "host name". | Names must be unique within the first six characters. Searching the map files in [.DATA.MAPSRC] is a good way to find out if your candidate name is already taken. [1] The uucp world lives almost exclusively in lower case. The uucp Mapping Project (about which more later) has this to say on the subject of host names: Host names may contain the following characters: "a" through "z", "0" through "9", and "-" (dash). Fully qualified domain names may contain "." (dot). No other characters, including uppercase alphabetics and underscore, will be accepted anywhere in the name. In addition, host names ___ ... may not end with a dash. | | Some uucp hosts use their domain names (which include dots) as | their uucp host name. You can't do this with DECUS uucp, and you | can't use DECUS uucp to talk to other sites that do this. As far | as DECUS uucp is concerned, uucp host names may not include dots. Your host name should be in lower case everywhere it appears in uucp's configuration files, and also in your "map entry" (described in the next chapter). So should all other host names that appear in your configuration files, unless you have certain knowledge to the contrary. If your system is owned by a company, the company name (or an ____________________ [1] Murphy's Law, as applied to the theory of supply and demand: "All the good ones are taken." ARRANGING FOR UUCP CONNECTIONS Page 5-2 Choose Your Host Name abbreviation) is a good choice; it may not be very imaginative but it will be easy for people to remember. A DECnet node name (even if converted to lower case) is probably not a good choice for a uucp host name: It was likely chosen to be mnemonic for the machine within your company rather than for the company itself, and in any case the two namespaces are likely to overlap. Machine-type designations (like "ucbvax", an early example) are to be avoided: The type of machine you're running on isn't really important outside of your site, so the extra characters necessitate more typing without adding any information. Soon you will probably want to register your organization as an Internet domain, at which time your machine will acquire another name in the form sysname.orgname.com where sysname designates a machine within your company (and may in fact be a DECnet node name; this makes mail routing easier), orgname is likely the company name, and "com" reflects that you're a commercial site rather than military, educational, or other. More information on this is in a later chapter. For now ___ we are concentrating on getting one of your machines connected to one or a few existing uucp systems. Since the maps will always be at least a little bit out of date, there is always the possibility that you and some other new site will pick the same name at the same time. Also, there are sites that don't appear in the maps. Don't worry too much about this at this point -- pick a unique name based on the information you have, and mail your map entry to the map coordinators at Rutgers (as described in a following section). If there is a conflict you will be told, and it is easy to change your name later. (Of course, if you change your name, mail sent to the old name won't get to you, but if your old name conflicted with somebody else's, your mail won't necessarily get to you anyway...) 5.2 Getting A Connection You have to find at least one (hopefully nearby) site with which you will exchange uucp calls. The map files (in [.DATA.MAPSRC]) should give you a good start; use the DCL SEARCH command to look for your city name, area code, or zip code. (The README file in the maps directory will explain the format of the map entries.) Contact the indicated system administrator at several likely sites. Remember that you will most likely be an "end node" in the uucp world, at least at first. You are therefore relying on the generosity of many other sites to relay your mail. If you find yourself exchanging a lot of mail with a particular site, arrange to exchange calls with them directly. This is especially important if the other site is another of your company's offices; ARRANGING FOR UUCP CONNECTIONS Page 5-3 Getting A Connection you shouldn't "do business" on other people's phone line time. If you are in an isolated area, your nearest neighbor may be a long-distance call away. Generally l-d calls are handled on a cooperative basis: People pay for the calls they place, under the assumption that each new site on the net will add to the power and usefulness of the "group mind", and a few l-d calls are a small price to pay for the benefits. I've never heard of anybody billing anybody else for phone charges (other than the uunet, which is a for-pay service anyway). __ If your neighbor insists on making no long-distance calls, you can set up DECUS uucp to poll them, perhaps once a day. For mail the traffic is generally low enough that no one worries about it. If you want a full news feed (10 MB/day) at 2400 bps over long-distance, you probably ought to volunteer to make all the calls. | | There are also two commercial services which provide uucp | connections. If you don't have a nearby site that can give you a | high-speed connection, either of these can offer a real cost | savings as well as good connectivity. They are listed here in | alphabetical order; we have no direct experience with either. | | | 5.2.1 Performance Systems International | | PSI provides connections through local dial-in numbers in a large | number of cities around the country; you pay for the call to the | nearest (possibly local) number, and PSI bills you a flat monthly | fee beyond that. They can also set up leased lines for extremely | high-speed connections (at correspondingly higher costs, of | course). They can act as your Internet mail forwarder and mail | exchanger (described later). For information, contact | | Performance Systems International | 11800 Sunrise Valley Drive, Suite 1100 | Reston, VA 22901 | phone: (703) 620-6651 | FAX: (703) 620-4586 | email: info@psi.com 5.2.2 UUNET Uunet is a commercial venture operated by one of the Unix user's groups. There is a small monthly fee and access time charges, but uunet provides many valuable services, including archiving of material posted to the net, Internet domain name registry, and Internet mail forwarding. They are also the best-connected news and mail machine in the country. Uunet is reachable not only via direct dial-up lines, which all run Telebit modems, but also via a local call to a Tymnet PAD. ARRANGING FOR UUCP CONNECTIONS Page 5-4 Getting A Connection | Uunet also offers a "900 number" service which can be used for | retrieving files from their archive area. This can be used by | anyone with uucp (including DECUS uucp) software, without prior | arrangement with Uunet. Some information can be found in | [.DOC.UUNET] . To get complete, up-to-date information and an application form, send your U. S. Mail address to UUNET Communications Services P.O. Box 2685 Fairfax, VA 22031-0685 1-703-876-5050 (While you're at it, ask them to send information on Internet domain registry as well.) 5.3 Exchange Login Procedures You must exchange access information with the system manager at each site with whom you will exchange calls. (See the following chapter for guidelines on creating the required VMS usernames.) On your side, this will consist of your dialup access phone number(s), the VMS username and password that you want the site to use, your system password (if you have one), and any other information that they need to log in to your machine. They also need to give you similar information for their system. If you don't trust them with this information, you can arrange for uucp on your VMS system to call them periodically to see if they have work for you. Of course, this requires that they trust _____ you with their access information! The bottom line is that, unless you only place outgoing calls, you and the system administrators at your neighbor sites have to trust each other with this data. Bear in mind that these usernames will be strictly captive accounts; even if an intruder learns your phone number, uucp login username, and password from one of your neighbors, the worst they will be able to do is masquerade as your neighbor, perhaps sending you "aliased" mail messages, or at worst filling up your spool directory (at their expense for the phone call, if long distance). You can prevent this by using the "callback" feature of DECUS uucp, described in the next chapter. (The chapter on "Security Issues" has more information about DECUS uucp's security precautions.) If your prospective network neighbors are unfamiliar with VMS, or if you have an unusual dialin environment (perhaps your modems are attached to terminal servers or port selectors rather than directly to the VAX, requiring several steps before the dialin user gets to a Username: prompt), you will also have to tell them how to use the username, password, etc., to log in to your system. Similarly, your first network neighbors will probably be Unix systems, and if you aren't familiar with Unix, be sure to ARRANGING FOR UUCP CONNECTIONS Page 5-5 Exchange Login Procedures get complete information for negotiating the login sequence. A good way for both of you to be sure you have all of this right is to set up guest accounts for each other and let each other log in as ordinary interactive users. If your neighbor isn't running DECUS uucp, s/he will probably want to exchange "chat scripts" with you. Explain to them that DECUS uucp implements the same function as chat scripts, but in a different way. They will probably grumble a bit, but on the other hand they may be jealous if you describe our "script files" to them, so don't feel bad. (If you're interested, complete ________ ____ information on Unix uucp chat scripts appears in Managing uucp ___ ______ and Usenet.) CHAPTER 6 CONFIGURING DECUS UUCP This chapter describes how to set up DECUS uucp to communicate with neighboring systems. 6.1 Create The Uucp Username(s) Create at least one UAF entry for the "uucp login". We will consistently use this term to refer to the VMS username via which ___ your neighbors on the net will log in to your machine (not to users on your machine who send or receive mail or news via uucp). The batch jobs that are part of DECUS uucp (uucico, uuxqt, and uuclean) also run under this account. The best way to set things up is to have one account for the local batch jobs, one for each of your uucp neighbors, and another for local testing. | | | 6.1.1 Using UUCP_CONFIG | | The command procedure [.BIN]UUCP_CONFIG will do everything | necessary to create these accounts. Invoke it from an account | that has write access to the UAF, and then: | | o Use option 1 to set up the account for local batch jobs | (UUCP_DAEMON), plus a template account (UUCP_DEFAULTS) | from which other accounts will be created. Both of | these will be placed in a previously-unused UIC group. | | o Use option 3 to add an account for each of your uucp | neighbors. 6.1.2 Manual Account Creation If you prefer, you can of course set up the uucp accounts manually. They should be an ordinary nonprivileged accounts (except for NETMBX and TMPMBX). Create a new UIC group, unused by anyone else on your system and outside of the system UIC group range (by default, this means the group number should be 11 octal or greater), for the uucp logins. CONFIGURING DECUS UUCP Page 6-2 Create The Uucp Username(s) (Later, when we set up NEWS, we will create another username in this group but with a different member number.) If you have more ___ ____ ___ than one uucp login, they should all have the same UIC (group and member number) and other characteristics (other than, of course, the username, password, and "Owner" fields). Automatic (timed) password expiration is probably a bad idea; no uucp (including this one) will know what to do if it logs in and is greeted with "Password has expired; change immediately with | SET PASSWORD"! Set the RESTRICTED, DISCTLY, DISMAIL, DISNEWMAIL, | DISWELCOME, DISREPORT, and DISRECONNECT flags for the account. | (Prior to Version 5.2, use CAPTIVE instead of RESTRICTED.) If you | have separate accounts for your uucp neighbors, they can be set | CAPTIVE even under 5.2 and beyond (the account for the local | batch jobs cannot be set CAPTIVE). | | We don't know the exact minimum values for all of the UAF quotas | that allow uucp to work. The following are known to work: [1] | | PRCLM = 2 TQELM = 10 | PRIO = 4 ENQLM = 30 | FILLM = 30 BYTLM = 15000 | BIOLM = 18 WSDEFAULT = 1500 | DIOLM = 18 WSQUOTA = 1500 | ASTLM = 24 PGFLQUOTA = 10000 Note that all "daemon" processes (those that run forever waiting for something to do, as opposed to being started only when there's work) purge their working sets before idling, so as not to tie up memory when they're not doing anything. Incoming uucp calls to your machine will start up fastest if you ___ modify your system-wide login command procedure to not print system announcement messages, fortune cookies, and so on when this user logs in, and if you suppress any SET TERMINAL/INQUIRE commands. (This is not absolutely necessary; some of us make no such efforts and communications to our uucp neighbors work fine. Some uucp systems, though, will choke if they have to wade through several thousand characters of announcements.) The default device and directory for this account don't matter; you could set them to the uucp spool directory (UUCP_DISK:[UUCP.SPOOL]). The LGICMD for this account must be UUCP_BIN:UUCP_LOGIN.COM . UUCP_LOGIN.COM is, of course, a captive command procedure. For interactive logins it executes a single image (uucico), and when that image exits, the process logs out. For batch the command procedure exits so the process can execute whatever command procedure is specified for the batch job. | | ____________________ | | [1] There may be slight discrepancies between this list, the | example account shown at the end of this section, and accounts | created by UUCP_CONFIG.COM. They'll all work, though. CONFIGURING DECUS UUCP Page 6-3 Create The Uucp Username(s) | Here is how the uucp login for one of simpact's neighbors appears | in the UAF. | | | Username: UU_CRASH Owner: Crash TimeSharing | Account: UIC: [11,2] ([UUCP_LOGIN]) | CLI: DCL Tables: DCLTABLES | Default: UUCP_DISK:[UUCP.BIN] | LGICMD: UUCP_LOGIN | Login Flags: Disctly Restricted Diswelcome Disnewmail Dismail Disreport | Disreconnect Captive | Primary days: Mon Tue Wed Thu Fri | Secondary days: Sat Sun | No access restrictions | Expiration: (none) Pwdminimum: 6 Login Fails: 0 | Pwdlifetime: (none) Pwdchange: 3-AUG-1989 20:57 | Last Login: 8-JUN-1990 01:31 (interactive), 26-MAY-1990 21:25 (non-interactive) | Maxjobs: 0 Fillm: 40 Bytlm: 20000 | Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 | Maxdetach: 0 BIOlm: 40 JTquota: 1024 | Prclm: 2 DIOlm: 40 WSdef: 1500 | Prio: 4 ASTlm: 50 WSquo: 2048 | Queprio: 0 TQElm: 20 WSextent: 4096 | CPU: (none) Enqlm: 50 Pgflquo: 10240 | Authorized Privileges: | TMPMBX NETMBX | Default Privileges: | TMPMBX NETMBX 6.1.3 Test Account We have found it useful to create an additional uucp login with the same UIC and privileges, but without the CAPTIVE and RESTRICTED flags and with LGICMD pointing to something that gets you to a DCL prompt. This "uucp test account" is not used for other systems to call in; in fact, you should disable dialup access for this account. Its purpose is to let you log in to the system using an account "just like" the one your neighbors use (except for username) and poke around to ensure that your protection masks, file ownerships, and ACLs are doing what they're supposed to, just in case uucico should ever manage to exit and leave the user with a DCL prompt. You can also use this account to run uucp outgoing calls from your terminal, watching the debug output on your screen; this will be described later. | | If you want to create one of these with UUCP_CONFIG, use option 3 | to create an account for a new "neighbor", and then use AUTHORIZE | to change the LGICMD, CAPTIVE, and RESTRICTED fields. CONFIGURING DECUS UUCP Page 6-4 Edit UUCP_SYSTARTUP.COM 6.2 Edit UUCP_SYSTARTUP.COM Inspect the file [.EXAMPLES.BIN]UUCP_SYSTARTUP.COM and edit it as indicated in the comments. Place the resulting file in [.BIN]UUCP_SYSTARTUP.COM . As stated in the comments, most sites will need to change only the first few entries. You can change everything all around if you like, but we don't recommend this because we haven't tested all the different permutations. We do recommend that you read the whole file to see what we're up to. 6.3 Create Your UUCP Map Entry In the map source directory ([.DATA.MAPSRC]), create a file that describes your connections to your network neighbor(s). The file should be called U.something; U.myhostname will do. The README _________ file in [.DATA.MAPSRC], together with the Appendix on pathalias, describe the format for a map entry. You should also browse through the existing map files to get a feel for the format. You'll find a file called U.simpact in [.EXAMPLES.MAPSRC]; this is simpact's "live" map entry at the time this document was ____ prepared. You can use this as an example, but be very careful to not copy it verbatim into [.DATA.MAPSRC]! Note also that you should not place lines like esther = .esther.acci.com or simpact simpact.com in your map entry unless you are actually registered as an Internet domain (that will come later). | | If one of your neighbors can act as a "smart host" -- that is, if | they can do uucp routing for you -- create another file, | [.DATA.MAPSRC]U.LOCAL_DATA, with the following line: | | smart-host = theiruucpname | | replacing, of course, `theiruucpname' with their actual uucp | name. Then delete, or save to tape and delete, all of the other | map files (except your own). 6.4 Create The UUCP Control File _______ The control file establishes parameters used by several parts of the uucp system; both uucico and uuxqt read it upon startup. [2] This file is supplied in example form in [.EXAMPLES.CFG]CONTROL. ; this is simpact's "live" control file. Please print a copy of this file before proceeding. CONFIGURING DECUS UUCP Page 6-5 Create The UUCP Control File All finished? Sorry, but we'll be doing a lot of that. It is much easier (not to mention less error-prone) to have you print out the actual files than to bring copies of them all into the text. You will be editing the example file to create [.CFG]CONTROL. NOTE ____ The programs that read the control file must find it under the name UUCP_CFG:CONTROL. (with no filename extension). There is no way to change this other than by editing and recompiling the source code. The format of each line in this file is extremely free-form. Parameter names start in column one, followed by any amount of whitespace (tabs and spaces), and then the value associated with the parameter. There is no provision for continuing lines, but none should be needed as all lines are quite short. Empty lines and lines starting with "!", "#", a space, or a tab, are ignored, and all other lines starting with unrecognized strings are simply skipped. The following sections describe the control file parameters which you will need to change for your system. Leave the rest of the file as it appears in the example unless you thoroughly understand the ramifications of what you are doing. 6.4.1 Hostname Edit the "hostname" line to contain your chosen uucp host name (same as the logical UUCP_HOST_NAME). NOTE In Version 0.2 of DECUS uucp, the parameter name for this was "nodename". We have changed it to avoid confusion with DECnet node names, since uucp host names and DECnet node names will generally be different. The code in the current version will still accept "nodename", but will write a warning message in the log file. ____________________ [2] This point is worth repeating: The file is normally read ____ only when the program starts up. By contrast, all of the other files described in this chapter are read "dynamically", whenever the program in question needs the information in the file. This is important because one element of the uucp system, the "uucico daemon", is intended to be started once upon system bootstrap and to run forevermore afterwards. There is a way, however, to force the uucico daemon to read the control file anew; see "Changing the Control File" later in this chapter. CONFIGURING DECUS UUCP Page 6-6 Create The UUCP Control File 6.4.2 Sleeptime The "sleeptime" parameter specifies the maximum time, in minutes, that the uucico batch job, or "daemon", will "sleep" between scans for reasons to call your neighbor systems. [3] The value shown, 15 minutes, seems to give a good balance between fast movement of work and system overhead. (A work scan consists of searching the spool directory for files called C.systemname_*, and usually only takes a few seconds per system unless the spool directory is very full.) 6.4.3 Debug The "debug" parameter specifies the classes of debug output that are written to the debug log files. It is interpreted as a binary mask; each bit corresponds to a class of debug messages. NOTE This parameter is interpreted according to the syntax rules for C integer constants, meaning _______ ______ ____ __ _____ __ ___ ______ that leading zeroes (one or more) in the number _____ __ __ __ ___________ __ _____ cause it to be interpreted in octal. If you prefer hex notation, change it to the form 0xhhhh, where hhhh represents any number of hex digits; the "x" may be in upper or lower case. In either case, at least one leading zero is required. If you eliminate the leading zeroes, the number will be interpreted in decimal. The value shown provides a trace of dial and login script processing and records any errors in the uucp protocol. This is the recommended setting if you are not involved in debugging the uucp software (as opposed to debugging connections to other machines). The bits in the mask are described in the comments in the file. 6.4.4 Port Provide a "port" line for each serial line which you intend to allow uucp to use for dialout. The format of this line is: | port ___ The angle brackets are metacharacters; they do not appear in the ____________________ [3] The actual mechanism used for the "sleep" is not hibernate/ wake (as might be inferred from the term "sleep"), but waiting for a local event flag. So, when the daemon is sleeping, expect SHOW SYSTEM to show it in LEF rather than HIB state. Uucico does use hibernate/wake in the protocol module, when it is actually communicating with a remote system. CONFIGURING DECUS UUCP Page 6-7 Create The UUCP Control File file. o As shown in the supplied example file, "port" is a literal string. It must start in the first column of the line. o is a uucp-specific name for the port, or for a class of ports (which is to say that multiple port entries can specify the same name). By convention we use "ACU" (short for Automatic Calling Unit, an archaic piece of AT&T hardware with which uucp was first used) to specify an autodialing modem. This is used to match port entries with entries in the systems file (described in the next section). o can be anything, but typically it is either "none" (for hardwired connections to other systems, perhaps in the same room) or the name of a type of modem. If this string is anything other than "none", uucp uses it as the extension of the file name for dial and hangup scripts for the modem in question. For example, with the control file shown, uucp will expect to find files [.CFG]DIAL.HAYES, HANGUP.HAYES, DIAL.TBGSPOOF, and HANGUP.TBGSPOOF. Scripts are described in detail in the next chapter. o and The and are the VMS device name of the serial port and the bit rate which the modem (or neighbor systems, for hardwired links) supports. If your modem supports multiple speeds (as most do), and you want uucp to use them, put several "ports" lines in the file, one for each speed but with the all other parameters the same. (Or perhaps not all the same. For example, some modems might need a special dial script to operate properly at one particular speed.) | | o | | This field is optional. If present, it contains one or | more characters which describe special characteristics | of the port and/or modem. In this version, only one | flag character is defined: | | L -- specifies that the modem uses a locked host | interface speed. If this flag is present, uucp will not | attempt to change the port's speed when placing an | outgoing call, regardless of the desired speed of the | connection. The field is then used only to | indicate which speed(s) the modem will support. The | modem is expected to do speed conversion between the | host interface's speed and the phone line. The actual | speed of the host interface is not specified here; it is | known only to the port itself (via a SET | TERMINAL/SPEED=nnn/PERM command, or equivalent command CONFIGURING DECUS UUCP Page 6-8 Create The UUCP Control File | to a LAT port) and to the modem. 6.4.5 Enbrmtrcv ___ This line is not in the supplied example file. If you want to allow other uucp systems to request that your system send files to them, in response to user-level "uucp" requests (as opposed to mail or news transfers, which are always initiated by the system which is sending the mail or news), add the following line to the control file: enbrmtrcv 1 Note that, even if this line appears in the control file, the only directory from which uucp will send files to other systems (or receive files from other systems, for that matter) is (at present) the spool directory, [.SPOOL] . 6.4.6 Changing The Control File It is worth repeating that the control file is only read when uuxqt.exe or uucico.exe starts up. For inbound calls this is no problem, as uucico.exe starts up anew for each such call. But if you have problems with outbound calls, and you believe that a control file change (perhaps a corrected "ports" entry) will fix _______ ____ things, remember that the uucico daemon has already read the file. You can stop the daemon's process with STOP/ID and restart it (the restart procedure is described later), or you can do the following from your terminal: $ COPY SYS$INPUT UUCP_REQUESTS: $READCTL ^Z This sends the message, "$READCTL", to the daemon's mailbox. (This is the same mailbox that is used by the uucp mailer to awaken the daemon when someone sends outgoing uucp mail.) Upon receiving this message in its mailbox, the daemon reads the control file as if it was just starting up. (The mailbox is world-writeable, but nonprivileged users on your machine can't use this to corrupt the daemon because they can't change the control file.) 6.5 Create The UUCP Systems File The systems file tells the uucp system who your neighbors are and how to reach them. The uucico "daemon" scans this file once each _____ time it is awakened. Each entry in the file describes a neighbor system. For each entry in the file, the daemon checks to see if the indicated remote system should be called, and places the call if appropriate. (The call decisions are described below with the description of the "times" field.) CONFIGURING DECUS UUCP Page 6-9 Create The UUCP Systems File The systems file is also used when uucp is handling an incoming call, but in that case only the line for the system calling in, and only a few of that line's fields, are important. An example systems file is supplied in [.EXAMPLES.CFG]SYSTEMS. ; except for phone numbers, usernames, passwords, and other access information, this is a copy of Simpact's "live" systems file. Please print a copy of this file before proceeding. As with the control file, you will be editing this file to create [.CFG]SYSTEMS. Each entry in the systems file consists of one or more lines, every line except the last ending with a backslash (\). (The \ ____ must be the very last character on the line, with no subsequent blanks.) Leading !'s, #'s, blanks, or tabs may be used to denote | comment lines. Comment lines beginning with !'s or #'s may | appear in between the lines of a single entry. The format of each entry is: \ \ ... This is a series of strings, or fields, separated by whitespace (any combination of blanks, tabs, and, if preceded by ______ backslashes, line breaks). No whitespace may appear inside any of the strings. (There is an "escape convention" to allow the encoding of whitespace within certain strings, should that be necessary.) The angle brackets denote syntactic elements; they do not appear in the file. When a line is continued, the "newline" between each pair of lines disappears completely; it does not appear as whitespace in the assembled entry (but if you have whitespace before the backslash or at the beginning of the new line, it is preserved). The following subsections describe each field in turn. 6.5.1 Field is the uucp host name of the remote system. Uucico will only call systems whose names appear in the systems file. In addition, it will normally not permit incoming calls from any system whose name does not appear in the local systems file. (You can circumvent this latter check by creating a systems file entry with an asterisk (*) for the system name. This would allow you to support "anonymous uucp" access, wherein you publish the telephone number and other information and allow anybody to call in and obtain copies of, for example, archived public-domain software which you keep on your machine. Several sites on the net provide this service.) CONFIGURING DECUS UUCP Page 6-10 Create The UUCP Systems File A single system might have multiple entries in the file, perhaps specifying different telephone numbers. When the daemon encounters the first entry for a given system, it sees if the system should and can be called according to the rules given by that particular entry. If the answer is yes, and the call is placed and is successful, all successive entries for that system are skipped. If the answer is no, or if the call attempt is unsuccessful, processing continues with the next entry, and the call decision is made according to that entry's fields. This repeats until either all of the given system's entries have been looked at, or a successful call is made. As shown in the example file, it is a good idea to use comments in the systems file to record information such as the name, voice telephone number, and so on, of the system manager at each of your neighbor sites. 6.5.2 Field is a string used to identify the system entry in certain log file records. A hyphen (-) will cause the system-name to be used; this is fine if you have just one systems file entry per uucp neighbor. If your systems file is more complex than that, putting a different entry-name on each entry will help to make the log file less ambiguous, as the log entries will show which systems entry was being used for each outbound call. 6.5.3 Field is the "uucp username" for the remote system -- the VMS username, on your system, which the remote system will use when it calls you. (We created these usernames in Section 6.1.) During incoming calls, uucico checks this against the actual username of the process, and terminates the connection if they don't match. If you don't want this checking to be performed for this particular entry, use a hyphen (-) as a placeholder. 6.5.4 Field is a list of characters which identify the link level protocols supported by the remote system. This parameter is not interpreted in the current software, but must be present as a placeholder. Put a lowercase `g' here for now, for compatibility with future versions. 6.5.5 Field may be `-' (as a placeholder) or one or more of: c callbacks required | px use parity x during login CONFIGURING DECUS UUCP Page 6-11 Create The UUCP Systems File xn set the debug level to n The c option indicates that, when the remote system calls in and logs in, the local uucico will not go ahead with the call but will instead hang up and then call the remote system back. With this enabled, even if someone else learns the uucp login username and password used by one of your network neighbors, they will be unable to call in and masquerade as your neighbor. | | The p option specifies the parity to be used when logging into | the remote system (processing the login script) during outbound | calls. The character x should be replaced by n (for no parity), | s (for space parity), m (for mark), e (for even), or o (for odd). | By default, no parity is used. Regardless of this option, no | parity is used for the dial or hangup scripts. (See the | following chapter on script processing for more information on | parity options.) The x option sets the debug mask to be used. If present, this overrides the value specified in the control file for the duration of the call (or call attempt) that uses the system entry in question. This feature is useful when difficulties are encountered with calls to or from only one of your network neighbors; debug log output can be kept to a minimum for all other systems. The characters immediately following the "x" are interpreted just like the debug value in the control file, which is to say that one or more leading zeroes denote octal notation, while a leading "0x" denotes hex. So to specify the debug value in hex, the complete field would look like x0x8F the first "x" being the flag character that says "set debug level", and the subsequent "0x" denoting hexadecimal notation. The example systems file includes a description of all of the debug control bits. NOTE The preceding are the only elements of the systems entry required to handle incoming calls; if you will not be calling out to the neighbor described in this entry, you can stop here. 6.5.6 Field The when string indicates when calls may be placed to the remote system. It takes the following form: [ssss-eeee][|[ssss-eeee]...][,succ[,fail[,poll]]] CONFIGURING DECUS UUCP Page 6-12 Create The UUCP Systems File The brackets (angle and square) denote syntactic elements, and should not appear in the actual file. Square brackets denote optional elements. o is a string consisting of one or more of the following day codes, all run together: Su Mo Tu We Th Fr Sa Wk Any Never "Wk" means any weekday (short for MoTuWeThFr), "Any" means any day at all, and "Never" means never call no matter what else appears in the string. ("Never" is useful for temporarily turning off calls to a system with a minimal change to the file, to wit, adding "Never" to the first days string.) o [ssss-eeee] , if present, indicates the start and end of the time interval during which calls may be made on the days indicated in the preceding string. The times must be precisely four digits long in military time format, and must be separated by a hyphen (-). If __________ ssss is greater than eeee, calls are disallowed from eeee to ssss. If no time range is specified, any time of day on the indicated days is considered to be okay to call. As indicated in the preceding format, the [times] element may be repeated any number of times, separated by or-bars (|). Examples are shown at the end of this section. The following elements of the field are optional. If present, they immediately follow the last (or only) [times] element, preceded and separated by commas (,). o is the minimum time (in minutes) that must elapse between a successful contact with the remote system (whether via incoming or outgoing call) and your system's next outgoing call attempt. If not specified, it defaults to 55 minutes. o is the minimum time (in minutes) that must elapse between a failed contact with the system and your system's next call attempt. If not specified, it defaults to 5 minutes. Uucico keeps track of how many successive failed contacts have occurred; if this number is greater than 1, the fail interval is multiplied by 1.5 raised to the power (nfails-1). This avoids a rapid succession of calls to a nonresponsive system (or to an incorrect phone number, no doubt someone's home, perhaps in the middle of the night). The maximum actual fail interval that will be employed is 10,000 minutes (about a week). With the default fail interval of five minutes, this is reached after about twenty calls. CONFIGURING DECUS UUCP Page 6-13 Create The UUCP Systems File o indicates how often (in minutes) your system will call the remote system in the absence of local work for that system. If not specified, defaults to 0, which disables polling; uucico then only places calls if your system knows that it has work for the remote system, relying on the other system to call in if it has work for your system. An extremely short , , or interval will not necessarily cause the uucico daemon to place calls at those intervals. At most, uucico will place one call for each entry in the systems file, each time the systems file is scanned. This occurs only when the "sleeptime" interval elapses or when someone | sends uucp mail, whichever comes first. Thus, if you really | want, for example, a poll interval of five minutes, you'll have | to change "sleeptime" in the control file to specify five minutes | (or less) between scans of the systems file. Once a call is established, all waiting work on both sides will be processed, regardless of which system placed the call. Here are some examples of valid "when" fields, with interpretations: Any Simplest possible "when" field. No day or time restrictions. Success and fail intervals default to 55 and 5 minutes: We won't call if we've had a successful call to or from them within the last 55 minutes, but if the last contact with them failed, retry every (5*1.5^(nfails-1)) minutes until we get through. No polling will occur. Any1800-2200 Calls can be placed on any day, but only between 6 and 10 pm. Again, success and fail intervals default to 55 and 5 minutes, and we don't poll. Wk1700-0600|SaSu,240,60,1440 Calls can be placed before 6 am or after 5 pm on weekdays, or any time on weekends. Success and (initial) fail intervals are four hours and one hour, respectively. If your system hasn't had a successful contact (incoming or outgoing) with them within the last twenty four hours (1440 = 24*60), call them even in the absence of outgoing work, in case they have work for us but can't call out for some reason. The day and time-of-day restrictions take precedence over the success, fail, and poll intervals. That is, the daemon first checks to see whether any calls at all are allowed according to the days and optional times fields; if so, it then makes the "need we call" decision based on the presence or absence of CONFIGURING DECUS UUCP Page 6-14 Create The UUCP Systems File outgoing work and the completion status and time of the most recent contact with the system. The success, fail, and poll intervals apply to all of the days and times restrictions, not just the last. None of the restrictions affect the times during which we will ______ accept calls from the system. (If you want that sort of control, you could use login time restrictions in the UAF entry for the remote site's uucp login, assuming that you use different usernames for different remote sites. A better approach is to ask the system manager of the neighbor system to only call you during the desired times; this prevents the neighbor system from logging "call failures" that really aren't.) If an outbound call ends in failure (perhaps due to a busy signal), and the uucico daemon encounters subsequent entries in the systems file for the same system on the same scan of the systems file, the call decisions are made as if the call had not been attempted, except that the fail interval is forced to zero. For example, if a system has several phone numbers that are not on a rotary selector, you can place an entry in the systems file for each number, with all other fields the same. If a call to the number given in the first entry fails, the daemon will go ahead and try the number specified in the next entry for that system, even though the fail interval specified in that entry (or the default fail interval of five minutes) will almost certainly not have elapsed. A failure is only logged once per scan of the systems file. (This only works if all of the entries for a system appear in sequence in the file, with no other systems' entries intervening.) There are two typical reasons for specifying day and time restrictions: To minimize uucp activity during peak load periods, and to force outbound long distance calls to be made when the rates are cheap. In the latter case, remember that your computer's clock might not agree with the phone company's, so it might not be a good idea to say that calls can be started at _______ exactly 6 pm (or whenever the desired rate period begins); allow five or ten minutes' slack. [4] When setting up a new connection, it is reasonable to use a field such as the following: Any,1,1 This will permit immediate outbound calls whenever you attempt to send mail, regardless of how recently a call succeeded or failed. (In case of failure, the one-minute fail interval will not cause uucico to retry immediately and forever, as the minimum "automatic" interval is set by the daemon sleep time.) ____________________ ________ ____ ___ ______ [4] This hint came from the book Managing uucp and Usenet. CONFIGURING DECUS UUCP Page 6-15 Create The UUCP Systems File 6.5.7 Field identifies the port, or class of ports, which may be used to contact the system. If the system is reached via a hardwired connection, this should be the that appears in the corresponding "ports" entry in the control file; otherwise it should be "ACU" (or whatever name you gave to your ports with autodial modems). If you want contacts with a particular system to use a particular type of modem, and matching on the supported speed isn't sufficient to make the selection (see the next section), you can invent a special port name. Add "ports" entries to the control file to specify the physical devices to which those modems are connected. 6.5.8 Field is the line speed which the neighbor supports. When the uucico daemon decides to call a system, based on a particular entry for that system in the systems file, it scans the control file for a "ports" entry with matching and fields. The fields must match exactly; "2400" is not taken to mean either "2400 or less" or "2400 or more". | | Uucico will set the line to this speed prior to attempting any | data exchanges with the modem, unless the port entry in the | control file includes the "L" flag. In that case the | field of the port entry merely tells uucico what speed the modem | supports, and the port is run at whatever speed has been | established by $ SET TERMINAL/SPEED=nnnn/PERMANENT. 6.5.9 Field is the number to dial to reach the system. You can include "W"s in the string to denote wait-for-dialtone and "P"s to denote a timed pause for two seconds, if your modem supports these functions. Use these characters regardless of the actual codes your modem wants in its dial command; they will be translated when the dial script is processed. | | The "W" and "P" characters must be uppercase to be recognized; | lowercase "W" and "P" will simply be passed through to the modem | as part of the dial string. 6.5.10 Field is the filename extension applied to UUCP_CFG:LOGIN. to derive the name of the script that will be used to log into the remote systems. Login (and other) scripts are described briefly in the next section; the following chapter provides a complete CONFIGURING DECUS UUCP Page 6-16 Create The UUCP Systems File description of the script language. 6.5.11 ... Fields are optional string parameters, available to the login script. [5] Note that no blanks or other whitespace per se may appear in these strings, but blanks may be specified as \s, tabs as \t, etc., as described under "Extended Strings" in the next chapter. If you want an actual backslash in one of these strings, use two backslashes in succession. Trailing unspecified parameters default to empty strings; a nontrailing empty string may be specified as "-" (a lone hyphen), and a string containing only a hyphen may appear as \- (that is, a backslash followed by a hyphen). | | | 6.5.12 Interaction Between The Systems File And Your Map Entry | | There isn't any. | | The systems file is used by the uucico program to place outbound | calls and to validate inbound calls. No calls will ever be | placed to, or received from, neighbors who do not have entries in | the systems file. | | The map entry (actually, your map file, plus all of the other map | files) is used by the command procedure MAKEPATHS to generate a | file called PATHS. This file, in turn, is used by the uucp | mailer to determine routes for outbound mail (and for | route-through mail for which no routing has been specified by the | sender). | | If your systems entry defines a neighbor who doesn't appear in | your map entry, you can send mail to them directly (by sending to | neighbor!username), but the mailer will never route mail to other | sites through that mailer. | | If your map entry defines a neighbor who doesn't appear in your | systems file, the mailer (and perhaps mailers on other systems!) | will attempt to send mail through that neighbor. Such mail will | be placed in your spool directory, where it will sit forever, or | at least until you notice it and clean it out. | | There is no automatic mechanism for ensuring that your systems | file and your map entry are synchronized, but for things to work | well, they need to be. If you change your systems file, be sure | to make corresponding changes to your map entry. 6.6 Script Files ____________________ [5] And to the dial and hangup scripts, for that matter, though they are typically only used with the login script. CONFIGURING DECUS UUCP Page 6-17 Script Files The final set of configuration files you will need are "script files". These tell uucico how to dial a remote system, how to log into the remote system, and (optionally) what to do to the modem at the end of the call. The script files provided should serve for the majority of applications (Hayes-compatible, Telebit, and several other types of modems, and logins for VMS and Unix systems, with and without terminal servers and port selectors). If these are not suitable for your situation, you will find a complete description of the script language in the following chapter. In any case, you will need to ensure that the following script files exist and are correct for your situation: 6.6.1 Dial Scripts For each different that appears in a "ports" entry in the control file, you will need a script file called [.CFG]DIAL. . This script tells uucico how to use that type of modem's autodial feature. For instance, for Hayes-type modems, the script (to simplify matters a bit) tells uucico to send "AT", wait for an "OK", and then send "ATDT" followed by the from the systems entry and a carriage return, and then wait for a response from the modem indicating success or failure. We have written two dial scripts, DIAL.HAYES and DIAL.TBGSPOOF. These have been tested with Hayes-type modems and with Telebit modems in g protocol "spoofing" mode, respectively. Several generous folks have sent in dial scripts for other types of modems; their names are listed in the comments in the respective files. 6.6.2 Login Scripts If the dial script ends in success, the uucico daemon then uses the specified in the systems entry for the called system to negotiate the login sequence (wait for "Username:" prompt, send username, etc.). The name of the login script used is [.CFG]LOGIN.extension, where the filename extension is given by the parameter of the current system entry. "Standard" login scripts are provided for typical VMS and Unix systems; the username, password, and system password are provided by the , , etc., fields in the systems entry. For special circumstances, such as systems which must be accessed through a port selector, you may have to devise your own login scripts; a sample of such a script is provided in [.CFG]LOGIN.SCUBED . CONFIGURING DECUS UUCP Page 6-18 Script Files 6.6.3 Hangup Scripts ___ Finally, for some s, you may need a script file called [.CFG]HANGUP. . This script, if present, is run at the end of each outgoing call through modems of the specified type. It tells uucico how to return the modem to a state suitable for accepting incoming calls. For example, in order to accept incoming calls under VMS, most modems must be ___ configured to not send "result codes" (strings such as RINGING, CONNECT 2400, and the like) to the local VAX, and so these modems are normally configured that way. But it is convenient to get result codes from the modems during the dial sequence, so the dial sequence starts with steps to turn result codes on. The hangup script is used to turn them back off again at the end of the outgoing call. (See the preceding chapter on modem setup options.) Some modems allow you to store your desired option settings in nonvolatile RAM, and will reset to these settings whenever the VAX drops the Data Terminal Ready (DTR) signal. Since DTR is dropped at the end of each call, even if uucico terminates abnormally, this provides a convenient way to ensure that the modem gets reset to the correct state. For such modems, hangup scripts need not be provided. Some other modems will work correctly for both outgoing calls and incoming calls with the same set of options; in this case no option changes are needed in the dial script, so no hangup script is needed either. One hangup script, HANGUP.HAYES, is provided; this turns off result codes for Hayes-type modems. (No hangup script is required for Telebit modems.) 6.7 Summary Here is a brief list of the steps required to set up uucp's configuration files: o Create one or more "uucp login" UAF entries, which your network neighbors will use for their calls to your system, plus one more for uucp batch job execution. o Create your "uucp map entry". o Edit the control file to specify your uucp host name, the work scan sleep interval, the default debug options, and the serial ports to be used for outgoing calls. o Create one or more entries in the systems file for each of your network neighbors. o Review, and modify as appropriate, the supplied dial, login, and hangup script files. CHAPTER 7 SCRIPT FILES DECUS uucp uses "script files" to direct modem dialing, login sequence, and modem reset operations. Script files are somewhat like DCL (or other CLI) command procedures, with some modifications as appropriate for this application. Formally, a script file describes a state machine; uucico interprets the script file [1] and does what the state machine tells it to. Before proceeding, please obtain listings of the script files in the [.CFG] directory (DIAL.*, LOGIN.*, and HANGUP.*) . The rest of the discussion will assume that you have these available for reference. 7.1 Script File Format ________ ______ Script files are ordinary text files containing comments, labels, __________ and statements. Comments are denoted by leading "!" or "#" characters. Some statements (those which do not end with an "extended string" argument; see below) can also have trailing comments. Labels begin in column one and are ended by colons (:). A label specifies a state name. All lines between a pair of labels are the statements for a single state. Processing always begins at the head of the script (no leading state name is necessary). Statements are divided into two categories, "action" and "waitfor". When a state is entered, all of its actions are performed in the order in which they appear in the file. A transition to another state may occur for any of three reasons: ____________________ [1] Technically the script is translated into an internal form first, but this process is so trivial that I can't bring myself to call it "compilation". SCRIPT FILES Page 7-2 Script File Format o One of the actions may cause a transition to another state, in which case the rest of the current state's actions (and any waitfors, if present) are skipped. Processing resumes with the first action statement of the new state. o If none of the actions cause a state transition, and there are no waitfors in the state, processing "falls through" to the next state in the file. o If none of the actions cause a state transition, but there are waitfors in the state, the state machine pauses until the conditions of one of the waitfors is "satisfied". It then transitions to the state named in that statement. Finally, there are two action statements which, when executed, cause the script to exit. 7.2 Script File Statements This section describes all of the statements that may appear in script files, except for a few special action statements. Those are described in a later section, "Overriding Defaults". Some statements accept one or two arguments, referred to in the following descriptions as "int", "ns", "str", or "xstr", to indicate whether the argument is an integer, a new state name, a string, or an "extended string" (described in a later section). ___ For all statements that accept two arguments, the first is the name of a new state, and the second specifies a condition or reason for changing to the new state. 7.2.1 Action Statements 7.2.1.1 Termination And Informational Statements log xstr send xstr to log file. logerr xstr send xstr to log file, with error indicator. failed exit script with "failed" status. success exit script with "success" status. 7.2.1.2 Sending Data dial send the string given by the field in the systems entry to the serial port. "W" and "P" characters in the phone number are converted as described under "dial strings", below. This statement also sets a default SCRIPT FILES Page 7-3 Script File Statements timeout value, as described under the "timeout" statement. send xstr send the string xstr to the serial port. sendstr int the argument of this statement is a digit from 0 through 7. Send the corresponding string parameter (, , etc.) from the systems entry (interpreted as an extended string). 7.2.1.3 Special Terminal Control Statements flush flush the terminal port's typeahead buffer. break send a break signal. hangup momentarily drop Data Terminal Ready on the serial port, causing the modem to hang up. (Not usually needed, since uucp does this at the end of each call.) 7.2.1.4 Counting, Branching, And Testing Statements sleep int delay for int milliseconds. zero clear the counter. count add one to the counter. ifgtr ns int go to state ns if counter greater than int. ifblind ns go to state ns if terminal multiplexer does not allow receipt of data when Carrier Detect absent (e.g. DMF32). ___ ifblgtr ns int go to state ns if counter greater than int and the terminal multiplexer does not allow receipt of data when Carrier Detect absent (e.g. DMF32). goto ns go to state ns unconditionally. ifstr ns int go to state ns if string parameter str is nonempty. ifnstr ns int go to state ns if string parameter str is empty. iflat ns go to state ns if terminal is a LAT port. ifnlat ns go to state ns if terminal is not a LAT port. SCRIPT FILES Page 7-4 Script File Statements 7.2.2 Waitfor Statements Waitfor statements are usually the last statements that appear in a given state, though in fact they can appear anywhere within the state. Even if they appear at the beginning, the script processor always does all of the action statements first. As a practical matter, the order of these statements is not significant; they are all interpreted "in parallel". ifcarr ns change to state ns if Carrier Detect is true. timeout ns int change to state ns if the time (in milliseconds) given by int has elapsed without satisfying any expects. If the time specified is 0, a default timeout value (calculated from the length and other characteristics of the most recent dial string) is used. expect ns xstr change to state ns if the string specified by xstr is received from the serial port. Case is significant, but high-order bits are not checked. ______ Multiple expect statements can appear within a state; see [.CFG]DIAL.HAYES for an example. | | NOTE | _______ | A timeout statement must appear within any state ______ ______ | that includes ifcarr or expect statements. | 7.3 Script Processing Details 7.3.1 Extended Strings In the statements that accept string arguments, the strings are interpreted as "extended strings". Extended strings begin with the first nonblank character and continue, including all imbedded and trailing blanks and other whitespace, until (but not including) the end of the line in the script file. (There is no provision for line continuation.) No trailing spaces should be present between the last "desired" character of the string and the end of the line, as they will be included in the stored string and sent or expected, just as they appear in the script file. And, obviously, no trailing comments are permitted! They will just be stored as part of the string. Within an extended string, the following "escape sequences" will be converted as indicated before being sent or expected: \d EOT character (control-D) \N null character \n line feed \r carriage return SCRIPT FILES Page 7-5 Script Processing Details \s space \t tab \- hyphen \\ backslash \ooo character with value ooo (in octal) Since extended strings in scripts can include imbedded spaces, tabs, etc., these escape sequences are only required in strings appearing in systems entries, though they may be used in script files to improve readability. The octal-character specification (\ooo) may have from one to three octal digits; it is terminated either after the third digit or when a non-octal character is encountered. But if you want to specify one of these followed by something that happens to be a valid octal character -- for example, a control-A followed by a 7 -- make sure to include all three digits after the \. (\0017 would become a control-A followed by the Ascii character "7", but \17 or \017 would become a control-Y (decimal value 25). \1S would convert to a control-A followed by an "S".) Extended strings are stored without a trailing carriage return unless one is explicitly present in the string (via \r). 7.3.2 String Parameters _______ The sendstr statement sends (after conversion from extended string format) one of the string parameters (, , etc.) in the current systems entry. The parameter is selected by the integer argument of the statement. This allows "generic" script files (such as LOGIN.VMS) to serve for many different systems; the string parameters in the systems entry provide the username, password, etc. Character substitutions described under "extended strings" above are performed on these strings. _____ ______ The ifstr and ifnstr statements allow further generality in script files, by testing whether a particular parameter is present in the systems entry. For example, a single script, LOGIN.VMS, can be used both for those VMS systems that require a system password and those that do not. The system password is specified as the string parameter in the systems entry; the script tests for this parameter's existence and skips the system password sequence if the parameter is empty. 7.3.3 "Wait" And "Pause" Characters In Dial Strings A different conversion is performed on dial strings. Dial ___ strings are not interpreted as extended strings. However, the characters "W" and "P" within a dial string are interpreted as "wait for dial tone" and "pause", and may be converted to other characters. By default, "W" is left alone, and "P" is converted to a comma (,); these are appropriate for Hayes-type modems. The SCRIPT FILES Page 7-6 Script Processing Details dial script may specify other substitutions (see below). Note that these characters must be in upper case to be recognized; lowercase "w" and "p" will be simply sent to the modem. 7.3.4 Default Timeouts For Dial Strings ____ When a dial statement is executed, a default timeout value is _______ set. This is the timeout value used by a subsequent timeout statement if the statement specifies a timeout value of 0. The default timeout is given by ctime + (ndigits*dgttime) + (nwchar*wtime) + (npchar*ptime), where ndigits, nwchar, and npchar are the number of digits, wait characters, and pause characters in the dial string, and ctime, dgttime, wtime, and ptime are 45 seconds, 0.1 seconds, 10 seconds, and 2 seconds, respectively. All of these times may be changed as specified below under "Overriding Defaults". 7.3.5 Trailing Carriage Returns Not Assumed ____ _______ In the dial and sendstr statements, the dial string or systems entry string parameter is sent with no trailing carriage return; if a carriage return must be sent after one of these, a separate ____ send statement must provide it. | | ______ | 7.3.6 Expecting Ambiguous Strings | | We've run into one modem that sends a simple "B" to indicate | "busy", or "Bnnnn" to indicate a connection at the indicated | speed (for example, B2400 for 2400 bits/sec). How would you | write a script to deal with this? | | The following | | dial | expect busy B | expect con_12 B1200 | expect con_24 B2400 | timeout nocarr 40000 | | won't work; if the modem sends "B1200" or "B2400", the first ______ | expect will be matched and the modem will be assumed to be busy. ______ | This is true regardless of the order of expect statements. | | A workaround for this particular situation is to not bother | checking for the "busy" case, and just delete the "expect busy B" | statement. If the called line is busy, the modem will only send _______ | a "B", none of the remaining expects will be matched, and the _______ | timeout statement will go to the "nocarr" state after 40 seconds. | | Here is a more general solution: | | dial SCRIPT FILES Page 7-7 Script Processing Details | expect got_b B | timeout nocarr 40000 | | got_b: | expect con_12 1200 | expect con_24 2400 | timeout busy 1000 | | | 7.3.7 Parity | __ | Most VMS systems use no parity (that is, eight data bits, no | parity bits, one stop bit, usually designated as 8N1) for async | terminal lines. DECUS uucp follows suit and uses 8N1 parity | during all phases of operation. | ___ | Once the uucp "shere exchange" has started, all uucp "g" protocol | implementations use 8N1, as a fully-transparent eight-bit data | path is required by the protocol. | | Some Unix systems (and a smaller, but nonzero, percentage of VMS | systems) have their terminal lines set for other than no parity. | Many Unix systems, for example, expect logins to use even parity. | | The script processor makes several allowances for parity for | outbound calls. | | The high bit of all incoming data is set to zero before matching | against "expect" strings, so it doesn't matter to us whether the | remote system is sending parity or not. | | As for the data we send, most systems, even ones that send us | characters with parity, are "forgiving" and will permit logins | from no-parity sources. However, if a system requires you to use | parity when logging in, For inbound calls, VMS is "forgiving" -- | the high bits of the username and password are zeroed before | comparison. | | As described in the previous chapter, the "p" option in systems | entries specifies the parity to be used when sending data from | the login script. | | Despite the "p" option, dial and hangup scripts will still be run | with no parity. Almost all VMS systems use eight data bits, no | parity, so we expect that most modems connected to VMS systems | will be set up that way. | | The script language provides five statements for changing the | parity to be used to send characters. These may be used in dial | and hangup scripts (if yuo absolutely must run your modems with | other than no parity), or in login scripts, if parity must be | changed "on the fly": | | parity_none set to no parity (8N1) SCRIPT FILES Page 7-8 Script Processing Details | parity_space set to space parity (7 data bits, high bit | forced clear) | | parity_mark set to mark parity (7 data bits, high bit forced | set) | | parity_even set to even parity ("A" is sent as 11000001, "C" | as 11000011) | | parity_odd set to odd parity ("A" is sent as 11000001, "C" | as 01000011) | | NOTE | | If you are one of those rare VMS sites that uses | something other than no parity for your | interactive terminals, we strongly advise you to | reconsider. The use of anything other than eight | data bits, no parity bit, on VMS terminal lines | invariably causes more problems than it solves. | | | | 7.3.8 Ambiguous Labels | | If you have two or more states with identical labels, only the | first will be recognized; it will be impossible to change state | to the others (other than by "falling through" from the | immediately-preceding state). The script processor will emit no | error messages for duplicate state names. 7.3.9 Overriding Defaults The script processor sets several default values upon beginning a script. The following statements, which override these defaults, may be useful in certain circumstances. chrdly int Since many modems cannot accept dialing commands at full "computer speed", the script processor sends all strings with a brief inter-character delay. This statement specifies the delay time, in milliseconds. The default is 100 (0.1 second). pchar str Specifies the character to which "P"s in the dial string should be converted. Default is ",", for use with Hayes-type modems. ptime int Specifies the time, in milliseconds, to allow in the default timeout for each pause character in the dial string. Default is 2000 (2 seconds). wchar str Specifies the character to which "W"s in the dial string should be converted. Default is "W", for Hayes modems. SCRIPT FILES Page 7-9 Script Processing Details wtime int Specifies the time, in milliseconds, to allow in the default timeout for each wait-for-dialtone character in the dial string. Default is 10000 (10 seconds). dgttime int Specifies the time, in milliseconds, to allow in the default timeout for each digit character in the dial string. Default is 100 (0.1 second). ctime int Specifies the time, in milliseconds, to allow in the default timeout for carrier to appear after the dial string is sent. Default is 45000 (45 seconds). 7.4 Written Any Good Scripts Lately? If you come up with any new script files, please send them to us. Scripts to deal with PC-Pursuit, various types of port selectors (both at your end and at the target system), and so on, would also be valuable. CHAPTER 8 FINISHING AND TESTING THE INSTALLATION OF UUCP | 8.1 Check SYSGEN Parameters | | Change the following SYSGEN parameters, as necessary: | | o TTY_ALTYPAHD or TTY_TYPAHDSZ must be at least 210 bytes | (see the chapter on configuring terminal ports). | | o Ensure that the lower three bits of TTY_DIALTYPE are | zero, unless you have certain knowledge that they should | be otherwise. | | o VIRTUALPAGECNT must be at least 20000 pages. 8.2 File Protection | Invoke [.BIN]UUCP_CONFIG and use option 2 to set the correct | ownership and protection codes on the files in the [UUCP...] | tree. Note that as a practical matter, there is no point in denying world read access to any of uucp's executable images, or indeed to any of the files supplied with the package, since anybody in the (literal) world can obtain copies of them from DECUS. 8.3 Define UUCP Logical Names Execute the following DCL command: $ @ddcu:[UUCP.BIN]UUCP_SYSTARTUP LOGICALS The parameter causes the procedure to only define the logical names, some of which are needed in the next step. 8.4 Generating The Path Data Base In this step you will create the file [.DATA]PATHS. , which tells the mail router how to reach other sites in the uucp mail network (and in the other networks to which there are uucp gateways). To do this, enter either of the following DCL commands: FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-2 Generating The Path Data Base $ @UUCP_BIN:MAKEPATHS or $ SUBMIT/NOPRINT UUCP_BIN:MAKEPATHS The account from which this is run should have a paging file quota (PGFLQUOTA) of at least 20,000 blocks, and access to a working set of 4K pages or so. On my system, an 8200, MAKEPATHS took about twenty minutes of CPU time, and thirty minutes elapsed time. The batch method is obviously preferable unless you have a spare terminal handy. | | If MAKEPATHS ever terminates with an access violation, it needs a | larger VIRTUALPAGECNT, more PGFLQUOTA, or both. | | As supplied, MAKEPATHS is memory-intensive. You can make it use | more disk space and less memory for its working files by defining | the logical name UUCP_MAKEPATHS; see the comments in | [.BIN]MAKEPATHS.COM for details. | | If you have defined a "smart host" (see the preceding chapter on | configuration files, or the later appendix on Pathalias), you | still need to run MAKEPATHS, but with only two short map files to | read (yours, and the one declaring your smart host) it should | take less than a minute to run. NOTE If you ever modify [.DATA]PATHS. by means other than running MAKEPATHS, ensure that the result is a streamlf file. 8.5 Start It Up Take a deep breath, log in to a fully-privileged account [1] (though you can turn off BYPASS), and execute UUCP_BIN:UUCP_SYSTARTUP. It will: o Submit the UUCICO_CALLOUT batch job, which runs uucico in "daemon" mode. Uucico will look for outbound work (mail or news) for all neighbor systems named in the systems file. It will attempt to call any neighbor systems for which (a) outbound work exists or (b) polling has been enabled in the systems file entry. After this, the "daemon" will "sleep" (enter LEF wait state) until the "sleeptime" interval from the control file has passed, or until someone sends outgoing uucp mail, whichever comes first. ____________________ [1] We have not had time to determine just what the minimum set of privileges is for running UUCP_SYSTARTUP. It is intended to be run from the system-wide startup command procedure, which is fully privileged anyway. FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-3 Start It Up o Submit the UUXQT_BATCH batch job for execution. This will run uuxqt.exe, which in turn will spawn a subprocess running uuxqt_dcl.com. Uuxqt.exe will then look for "X" files in [.SPOOL]; finding none, it will hibernate. o Submit the UUCP_CLEANUP batch job for execution one hour later (this will resubmit itself every hour). 8.6 Test It You should be able to "bounce" mail off the other machine. Invoke MAIL, type the SEND command, and enter the following in response to the "To: " prompt: UUCP%"neighbor_hostname!my_hostname!my_user_name" and it should be sent to the other machine and echoed back. As soon as you send uucp mail, your uucico daemon should place the appropriate call (unless call time restrictions prevent it from doing so right away). For other tests, send mail to the postmaster or to your contact at your neighbor system. Details on address formats can be found in one of the Appendices. ___ Note that "looped" mail is generally not echoed within the same call in which it was sent. | | You can also test local mail delivery by sending mail to | | UUCP%"my_hostname!my_user_name" | | This involves only uuxqt, not uucico. 8.7 If The Call Doesn't Work The most common reasons for this will be file protection troubles and call/login problems. Look in the debug file (described in the appendix on "Troubleshooting") for information on what happened. If you prefer, you can run the call from your terminal, and watch the debug output appear "live". To do this, invoke the UUCICO_CALLOUT command procedure interactively, as follows: $ @UUCP_BIN:UUCICO_CALLOUT "neighborname" neighborname must be in lower case and surrounded by quotes, as shown. You may prefer to do this via SET HOST 0/LOG, at a hardcopy terminal, or by some other means which will let you preserve the entire session. Running uucico this way bypasses all retry period and call time checking. FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-4 If The Call Doesn't Work NOTE You should do this only from your uucp test account, as this account has the same privileges (none), UIC, and other attributes as the account under which the uucico daemon normally runs. Testing under any other account may introduce other problems or invisibly get around the original problem (usually due to file protection, UIC differences, and other factors). Another way to stimulate a call without actually sending mail is to run the uupoll program. Define uupoll as a foreign command by executing [.BIN]USERCMDS.COM, and then: $ uupoll neighborname This will create a dummy C-file in the spool directory and awaken the daemon. The daemon should call the indicated system. At this time there will be no work waiting at either side, so the two systems will say hello, say goodbye, and hang up. Check the log file and debug log file (see the "Troubleshooting" Appendix) to see what actually happened. This method of inducing a call ___ does not bypass uucico's retry period and call time checking; if we just tried to call the indicated system a few minutes ago, nothing will happen until the relevant retry period (success or failure, depending on how the previous call ended) has expired. 8.8 Make It Automatic When you are happy with things, put a command to execute ddcu:[UUCP.BIN]UUCP_SYSTARTUP.COM (with no parameter) in your site-specific system startup command procedure. (Remember that UUCP_SYSTARTUP.COM defines the logical UUCP_BIN, so you can't use the logical to find the right disk at boot time!) To make the tail, News, and other commands available to users, place a command to execute UUCP_BIN:USERCMDS.COM in your site-wide login command procedure. | | | 8.9 Note For Cluster Users | ___ | All machines in the cluster (all those that are to have access to | uucp mail, at any rate) should execute UUCP_SYSTARTUP.COM upon | startup. This procedure automatically checks the node name | against the name defined by the logical UUCP_BATCH_NODE . If | they're the same, it does everything; otherwise, it just defines | the logical names and installs the mail shareable images. FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-5 Tell Your Users 8.10 Tell Your Users After you have things working reliably and have some experience sending and receiving network mail, you will want to tell the other users at your site about it. The "Address Formats" appendix should provide most of the information they will need to send and receive mail. You will likely want to customize it for your site. There is a HELP module describing uucp mail in [.DOC]UUCP_MAIL.HLP . Again, you will probably want to customize this a bit for your site. You can include it in the standard VMS DCL-level help library (SYS$HELP:HELPLIB.HLB) or place it in an alternate help library (accessed via a logical of the form HLP$LIBRARY_n). 8.11 Tell The World Mail a copy of your map entry to: uucp%"rutgers!uucpmap" or to the address specified in [.DATA.MAPSRC]README . Within a month or so it will appear in an update to the appropriate U.xxx file, will be distributed via the network News to all interested parties, and so will be reflected in everyone's PATHS. databases, allowing other folks to easily send mail to you. By that time you should have News running (see the chapters on adding News support), so you'll get a copy too, as well as updated maps for many other sites. 8.12 Tell Us ______ Please send mail to one (or all) of the VMSnet team. This needn't be an elaborate missive; a copy of your map entry will do just fine! Of course, comments on any difficulties you _______ encountered (and how you resolved them) would be greatly appreciated. (See the front cover for addresses) 8.13 Obtaining Current Maps Regardless of how you obtain this package, the maps that come with it will be a little (or maybe a lot) out of date. They will probably be good enough to get you going, but you should arrange | to get a new set as soon as possible (unless, of course, you're | relying on a smart host). | | One of your prospective network neighbors should be able to | supply you with a more up-to-date set of maps. If they are | running the Unix operating system, ask them to put the maps onto | a "tar" (tape archive; somewhat analysis to VMS's BACKUP) tape. | The program [.BIN]TARREAD.EXE will read such a tape; instructions | are in [.DOC.UTILS]TARREAD.DOC . After recovering the files from FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-6 Obtaining Current Maps | the tar tape, use RENAME commands to change the underscores (_) | in the file name extensions to hyphens (-). (Sorry about that; | the uucp map files use multiple periods in their names. We used | one convention for converting the filenames to VMS format, and | the folks who wrote TARREAD used another.) | | You can also use your uucp system to retrieve reasonably up-to- | date maps from uunet via their 900 number, even if you are not a | uunet subscriber. Instructions on the 900 service are in | [.DATA.UUNET]. At this writing, the cost to retrieve the maps is | about eight dollars with Telebit modems. The following procedure | will retrieve the entire map database (about 1.7 megabytes): | | $ uucp "uunet!~/uumap.tar.Z" "uumap.tar-Z" | $! (case is significant in the first file name above) | $ set default uucp_spool | $ compress -d uumap.tar | $ define tape uucp_spool:uumap.tar | $ set default [uucp.data.mapsrc] | $ tarread == "$uucp_bin:tarread" | $ tarread xv | | Again, the files will come out with names like U.USA_CA_1 | (TARREAD's convention) instead of U.USA-CA-1 (our convention); | you'll have to rename them. You can then delete | uucp_spool:uumap.tar. | | You can also ask uunet for individual map files for your area. | For example, to retrieve u.usa.ca.1, the command | | $ uucp "uunet!/usr/spool/ftp/uumap/u.usa.ca.1" "u.usa-ca-1" | | will place the file u.usa-ca-1 in UUCP_SPOOL:. Rename it into | [.DATA.MAPSRC] and you're done. When you are set up to receive News, you will get map updates in the newsgroup comp.mail.maps . The News/uucp integration mechanisms supplied with DECUS uucp will extract these into [.DATA.MAPSRC] and submit MAKEPATHS for execution, so that PATHS. will be kept up to date automatically. 8.14 Adding More Neighbors Soon you will probably want to add more neighbor systems. Here is a checklist of things to do: o Create a uucp login for the new neighbor. o Exchange phone numbers, usernames, passwords, and other access information with the neighbor system manager. o Add one or more entries to your systems file. FINISHING AND TESTING THE INSTALLATION OF UUCP Page 8-7 Adding More Neighbors o If an existing login script isn't suitable, create an appropriate one. o Test the link by sending mail to a known user on the neighbor system, or by "bouncing" mail through the neighbor back to yourself. o Update your uucp map entry to reflect the new connection, run MAKEPATHS to rebuild your local routing database, and mail the new map entry to rutgers!uucpmap . CHAPTER 9 REGISTERING AS AN INTERNET DOMAIN After you have things running well and reliably, you should consider registering your organization as an Internet domain. Note that sending your map entry to rutgers and seeing it come ___ back in the appropriate posting in comp.mail.maps does not constitute Internet domain registry. 9.1 Why Should I Become A Domain? There are several good reasons for becoming an Internet domain. 9.1.1 Acquiring An "@-style" Address As a user on a machine within an Internet domain, you can legitimately publish your "net address" on your business card, your postings on DECUServe, etc., as user@host.company.com (or whatever). A lot of non-registered sites who are in the uucp maps use things like user@host.uucp, and while this will sometimes work (especially from uucp sites, but also from some Internet sites) it is not officially correct. (This is discussed in a bit more detail later.) 9.1.2 Better Mail Connectivity Anyone else who handles Internet domain-style addresses correctly will be able to send mail to you, even if they've never heard of you before, and even if they don't use the uucp maps. Here's how: If their machine doesn't know how to send to "host.company.com", it then tries "company.com"; if that fails, it asks its "nameserver" (another machine on the Internet, which either keeps or has access to up-to-date routing information for all registered domains) how to reach your domain. If you are properly registered, the nameserver will respond with instructions to send the mail to the Internet site designated as your "forwarder". REGISTERING AS AN INTERNET DOMAIN Page 9-2 Why Should I Become A Domain? Your forwarder then sends the mail to the designated "gateway" for your domain -- probably your uucp machine -- and your gateway then figures out how to get the message to the correct host within your domain. This is the whole point of your managing your own domain: The nameservers don't need to know how to reach any of the machines in your domain other than the domain gateway. 9.1.3 Supporting An Internal Network If you have several machines in your company, perhaps connected to your uucp machine via DECnet (or other mechanisms), and you want users on those machines to be able to send and receive uucp mail, becoming an Internet domain lets you avoid publishing separate map entries for them all. They can become machine1.company.com, machine2.company.com, and so on. Once you are registered as "company.com", you need do nothing else externally to set this up -- just arrange for the proper forwarding to and from the machines in your domain, and add their names to your uucp machine's map entry, so the rest of the net will know that they can be reached through you. (DECUS uucp provides for such forwarding, as described later in this chapter.) 9.2 Why Do I Need A Forwarder? At this point many people wonder why each Internet-registered uucp host must have a designated "forwarder": Why can't the Internet simply send any mail destined for user@host.company.com to a single designated forwarder, which would deliver it to uucp hostname "company"? There are several reasons why this wouldn't work: First, there is no guarantee that the uucp hostname and the second-level domain name ("company" in this example) will be the same. Your particular site has to have an entry in the forwarder's routing tables specifying the uucp hostname for your domain's gateway machine. Second, there's no reason to suspect that "company.com" is even reachable via uucp; forwarders usually support many different transport mechanisms. Again, your domain must be entered in the forwarder's routing tables, with a field specifying delivery via uucp. Finally, if there were a single Internet/uucp forwarder, it would have to carry an unreasonable amount of traffic. In self-defense (mostly to avoid having to answer hundreds of "how do I send mail to uucphost!user" questions from their users), many Internet sites have set things up so that mail sent to "user@uucphost.uucp" from one of their machines will be sent to a known Internet/uucp gateway, with the addresses set up so that the gateway recognizes the target machine as a uucp host, and so just sends the mail via uucp to uucphost!user. This works REGISTERING AS AN INTERNET DOMAIN Page 9-3 Why Do I Need A Forwarder? ___________ because in this case the originating machine knows the uucp hostname, and so can construct the address properly. It works __ best if the originating machine is the Internet/uucp gateway in question. But, as we've said before, this use of ".uucp" as an unofficial domain name is fraught with peril, since ".uucp" also happens to be an officially registered zone. 9.3 How Do I Register? There are currently two good ways for uucp sites to become Internet domains. One is registry through the "uucp zone", which is administered for the Network Information Center by Uunet. This is probably the more appropriate method if you will be setting up a domain with more than one machine in it. The file [.DOC.DOMAINREG]UUNETREG.TXT has details. NOTE The uucp zone was formerly administered by Stargate Information Services, but this function has been taken over by uunet. The other method is to register your machine(s) in the "US domain". This seems to be more appropriate if you expect to be running just a single machine. See [.DOC.DOMAINREG]USDOMAIN.TXT . There are other files in [.DOC.DOMAINREG] which provide additional information on the domain registry process and on domains in general; see [.DOC.DOMAINREG]AAAREADME.TXT . In either case you will need to find a "forwarder" -- a machine that can forward mail sent to you from the rest of the Internet. There are two points about forwarders which seem to be poorly understood (at least, a lot of people seem to have misconceptions about these points): o First, the forwarder must be a "real Internet" machine, meaning that it must be connected via TCP/IP to the rest of the Internet. This is because Internet sites, upon finding out from the relevant nameservers that mail to you is to be sent to your forwarder for delivery, will ___ ______ attempt to send the mail to your forwarder via TCP/IP. o Second, you need not have a "direct uucp" connection to your forwarder. For that matter, the forwarder need not use uucp at all to forward your mail; DECnet or TCP/IP, for example, will work fine. If your forwarder does use uucp to send mail to you, a direct (one-hop) connection is obviously preferable, but is not required. REGISTERING AS AN INTERNET DOMAIN Page 9-4 What Then? 9.4 What Then? Okay, you've sent off your application form and received confirmation that your new domain is active. Now what? 9.4.1 Update Your Map Entry The "#N" line in your map entry stays the same. Add a line of the following form: #F for1.company.com[,for2.co2.com...] where "for1..." are the Internet name(s) of your forwarders. (Yes, you can have more than one. I'm not sure why you'd want this unless one of them is unreliable.) In the pathalias data, add uucpname .yourcompany.com and uucpname = machname.yourcompany.com uucpname = yourcompany.com making appropriate substitutions for all elements. The first (note the leading period!) is a domain gateway declaration to pathalias (the program that interprets the maps), declaring "uucpname [your uucp hostname] is a gateway to domain _______ .yourcompany.com". The latter are name equivalences, or aliases, ensuring that pathalias can recognize any of the strings which represent your uucp host. (You have to be able to recognize your own name, however disguised.) Note that uucpname and machname might be the same name, but don't have to be; machname here might well be a DECnet node name. There is no concern here that a given "machname" might be used by other sites, since it is qualified by the rest of the domain name. The second of the two aliases shown allows people to send mail to users on the "uucp gateway host" at your company without knowing its machname. If you publish map entries for more than one machine, such an alias declaration is probably only appropriate in one of them. If you're going to take advantage of the ability to "hide" your internal network behind your domain, read the "Networks" section of the pathalias appendix, and change the map entry as appropriate. As usual, mail your updated map entry to rutgers!uucpmap . REGISTERING AS AN INTERNET DOMAIN Page 9-5 What Then? NOTE The file [.DATA.MAPSRC]README. is not entirely up to date on these points. 9.4.2 Change Logical Names In [.BIN]UUCP_SYSTARTUP.COM, change the definition of UUCP_DOMAIN_NAME to reflect your name. 9.4.3 Publish Your New Address You can now have business cards and so on printed that show your brand-new Internet address. One caution: Many Internet sites still do not use the name domain server, and others do not properly understand "MX" (mail forwarding) records, so for the widest possible acceptance, publish two addresses. One (the preferred one) will show just your "native" Internet domain name, and the other will show explicit forwarding. For example, if uunet (whose Internet name is uunet.uu.net) is your forwarder, and you are user@aridus.megacorp.com, you might publish the following addresses for yourself: user@aridus.megacorp.com user%aridus.megacorp.com@uunet.uu.net Make sure before you do this that your forwarder can handle names of the second form. (Uunet can do so, and most others can at least potentially do so, but ask to make sure that it's been set up.) 9.4.4 Set Up The Mail Address Rewrite File The mailer looks for a file called UUCP_CFG:MAIL_REWRITE.RULES for address rewriting rules. If this file exists, the mailer uses the rules in it to transform addresses from one form to another. These can be used to allow mail sent by users on your internal network (which probably uses a non-Internet style addressing syntax) to go out to the net in "standard" form. You can also use them, in some cases, to repair particular addresses that are giving you or a downstream mailer some trouble. An example rules file (from dcs.simpact.com) is included in ___ [.EXAMPLES.CFG]. Do not use this file as-is! Print it out and study it while reading this section, and use it as a basis for your own rules file. NOTE The basic functionality of the address rewriter was extracted from ANU NEWS. Except for the addition of the 4 rule sets, the rewriter works REGISTERING AS AN INTERNET DOMAIN Page 9-6 What Then? just like the one in NEWS. You cannot, however, use NEWS's rewrite rules file, as NEWS's rewriting is performed in a different context. 9.4.4.1 Rule Sets There are four rule sets that are applied to addresses at various points in the mailer. The rules for all four sets are given in the rewrite file. These rule sets are: 9.4.4.1.1 Inbound-To - The target address in the uucp envelope (rmail command in the X file) is processed for possible rewriting. The primary purpose here is to allow qualified domain addresses to be converted into whatever local syntax will achieve delivery. For example, at Simpact, "jeh@onyx.simpact.uucp" can be rewritten as "onyx::jeh" since "onyx" is connected to "simpact.uucp" via DECnet, and our DECnet node names are used for the lowest-level domain names. The rewrite rule *@*.simpact.com \002::\001 takes care of all such cases. NOTE The "To:" header in the message body is NOT processed by the mail address rewriter. 9.4.4.1.2 Outbound-From - Outbound from rules are essentially the inverse of the inbound-to rules. That is, they allow you to create qualified domain names from the "From" addresses given to you by the hosts in your domain. | | For example, at Simpact, when someone sends mail from | decnetnode::user, we want it to go out on the net with a "From" | address of user@decnetnode.simpact.com . The rewrite rule | | *::* \002@\001.simpact.com | | accomplishes this. 9.4.4.1.3 Inbound-From - The "From" address in an inbound message can be rewritten. You can use this to repair problem addresses, converting them into a form that can be replied to. REGISTERING AS AN INTERNET DOMAIN Page 9-7 What Then? | For example, at Simpact, mail that comes from CSNET sites arrives | with "From" lines of the form | | user%domainname@relay.cs.net | | which is unreplyable. But it invariably works if we send the | reply to user@domainname. So the rewrite rule | | *%*@relay.cs.net \001@\002 | | is used to strip off the "@relay.cs.net" and change the first "%" | to a "@". 9.4.4.1.4 Outbound-To - When an address is presented to the mailer for outbound delivery, it can be processed by the rewriter before being routed via the PATHS. database. This can be used to "handcraft" routes to hard-to-reach sites where the normal automatic routing does not produce a valid path. | | For example, mail sent to Bitnet sites (user@machine.bitnet) goes | to a Bitnet gateway. The particular gateway is automatically | selected via the uucp maps. Unfortunately, the gateway that is | usually chosen at Simpact can't seem to handle many Bitnet | addresses. But we know that cunyvm.cuny.edu is a Bitnet gateway, | and mail sent through there has never failed. So the rewrite | rule | | *@*.bitnet \001%\002.BITNET@cunyvm.cuny.edu | | is used to force the use of this gateway. | | After the mailer performs an outbound-to transformation it looks | at the resulting address to see if it contains a "!". If it | does, it assumes that the address contains a complete uucp ___ | bang-path, and so will not pass the address to the standard | router (for routing via PATHS.). If the rewritten address does | not contain a "!", or if no transformation was performed, the | address is passed to the router. | | This convention allows a special kind of rewrite rule which is | useful for directing mail to one of your uucp neighbors for | routing. Suppose, for example, that site "router" is one of your | uucp neighbors and that they can handle ".bitnet" addresses well; | you might want to use the following outbound-to rewrite: | | *@*.bitnet router!\001@\002.bitnet | | The result of this rewrite will be a "mixed mode" address. In | this case (only) DECUS uucp will interpret such an address as | "send to uucp host 'router', and ask them to send the mail to | \001@\002.bitnet". REGISTERING AS AN INTERNET DOMAIN Page 9-8 What Then? 9.4.4.2 Rewrite File Format Three types of lines may appear in UUCP_CFG:MAIL_REWRITE.RULES: comments, set selectors and rules. The first character of the line decides which kind of line it is. 9.4.4.2.1 Comments - If a line begins with a "#", it is a comment and will be ignored. 9.4.4.2.2 Set Selectors - If a line is surrounded by square brackets (that is, "[" ... "]"), it is a rule selector. The text inside the "[...]" declares that subsequent rules, until the next selector (or the end of the file), are to be placed in the given set. The text ____ within the "[...]" must match one of the following exactly (lowercase won't work): [INBOUND-TO] [OUTBOUND-FROM] [INBOUND-FROM] [OUTBOUND-TO] If the selector is not valid, the rules following it are ignored. NOTE At the present time, there is no report sent anywhere when a bad selector is encountered. 9.4.4.2.3 Rules - Anything else in the file is assumed to be a rule. A rule consists of two fields specifying an input pattern and an output pattern. Any amount of whitespace separates the two fields. The input pattern may contain wildcards - a "?" matches a single character and a "*" matches a substring. _______ When an input pattern is matched, the output pattern is applied. Text is copied from the input string to the output string using the rule given in the output pattern. Special flags in the output pattern will be replaced by corresponding wildcard text from the input string. The flags are specified using a "\" followed by a three-digit OCTAL number indicating the position of the wildcard in the input pattern. Suppose you have the following rules: *!* \002@\001.my.domain *::* \002@\001.my.domain REGISTERING AS AN INTERNET DOMAIN Page 9-9 What Then? If these were declared as [OUTBOUND-FROM] rules, then the following transformations would occur on the "From" addresses in mail going out from your machine: marty!ta2 ==> ta2@marty.my.domain monica::ta3 ==> ta3@monica.my.domain Rules are tried in the order in which they appear in the file. The first one that matches terminates the search. This allows you you to place a catch-all rule at the end of all the rules in a given set. For example, this might be a set of [INBOUND-TO] rules: *@marty.acci.com marty!\001 *@esther.acci.com \001 *@acci.com \001 *@*.acci.com uucp_postmaster In this rule set, mail aimed at "marty.acci.com" is delivered to "marty" via uucp. "esther.acci.com" is the "acci.com" gateway, mail to that system should be reduced to just the name of the user. There are no other hosts in the "acci.com" domain, so mail to them should be forwarded to the postmaster for further action. Warning! The rule *!* \002@\001.my.domain makes for a nice example but lousy practice. Mail that was initiated by one of your uucp connections, and routed through you, may have a "From" address that will match the pattern. If that neighbor is not in your domain, you don't want to rewrite their "From" addresses. | | | 9.4.4.3 Suggestions For Rewrite Rules For Internet Domains | | (by Tom Allebrandi) | | If you have a registered Internet domain acting as a gateway to | only DECnet connected hosts, you should probably use | | [INBOUND-TO] | *@*.your.domain \002::\001 | *.your.domain!* \001::\002 | [OUTBOUND-FROM] | *::* \001@\002.your.domain | | If you have a mixture of conections (that is, some of the hosts | in your domain are reached via DECnet, and some are reached via, | for example, uucp), you will have to enumerate them. That is: REGISTERING AS AN INTERNET DOMAIN Page 9-10 What Then? | [INBOUND-TO] | *@dnhost.your.domain dnhost::\001 | *@uuhost.your.domain uuhost!\001 | ... etc ... | | If you do not have a registered Internet domain, you should use | the following for your DECnet hosts: | | [INBOUND-TO] | dnhosta!* dnhosta::\001 | dnhostb!* dnhostb::\001 | [OUTBOUND-FROM] | *::* yourhost!\001!\002 | | On the [INBOUND-TO] you cannot use | | *!* dnhosta::\001 because that | will intercept all messages passing through your host. On the | [OUTBOUND-FROM] side, you need to include your host name as it is | likely that you will not publish your DECnet host names. If you | do not publish your DECnet host names, you must give something | that is relative your gateway host. | | Note that this latter problem only applies to the RFC822 From: | address. The UUCP From_ line is self-relative (assuming that | every host that touches it handles it correctly.) 9.5 What If Another Machine In My Company Is Already Registered? Or, to put it another way, "What if my company already has an Internet domain name?" (See the next section, "Machines vs. Companies".) For example, simpact.com has been registered -- but not in the uucp zone; we have a small VAX running Unix with a real TCP/IP connection to the real Internet. [2] So I can't very well send off a domain registration form asking for "simpact.com"; not only will it be rejected as a duplicate name, but I'll look silly. ("Don't those people talk to each other?") I should feel relieved; I don't have to apply for a domain name. On the other hand, before I can publish my address as jeh@dcp.simpact.com (my uucp machine), I have to make sure that mail sent to the Unix machine will get here, and that mail which I need to send through the Unix machine gets sent there, and so on. This requires a communication link between the Unix machine and myvax (obviously uucp will work), and appropriate entries in the various configuration files on both sides. (We can't give more details because we haven't done it yet.) If the "machine that's ____________________ [2] The situation would be much the same if its connection to the world was via uucp. REGISTERING AS AN INTERNET DOMAIN Page 9-11 What If Another Machine In My Company Is Already Registered? already registered" is an Internet machine, you can go ahead and publish a uucp map entry reflecting your connection to it. If ___ it's connected to the world via uucp, its map entry should be ___ revised to reflects its connection to you. In this case there is no need for a map entry for your machine; the whole point of domains -- one of the whole points, anyway -- is to keep from having to publish map entries for all machines within a domain (in this case, within a company). If the link between the "already-registered machine" and yours is something other than uucp (perhaps DECnet/Ultrix, or some flavor of TCP/IP), please let us know how you did it. (We may be able to provide more help later; subscribe to the VMSnet newsgroups and watch for announcements and updates to the manual.) 9.6 Domain Names: Machines Vs. Companies Technically speaking, it isn't the machines that are registered (other than in the US domain). A name like acci.com doesn't refer to a machine, but rather to a company, organization, or other group of people responsible for the machines in the named domain. A lot of people get this point wrong, at least in casual conversation (and probably elsewhere in this document). Usually it doesn't matter; in practice, a domain name is registered to get a particular machine "known" to the network. Of course to do this the machine needs a name of its own; the domain name isn't it, so we tack on another name, for example esther.acci.com, meaning "machine esther in the domain acci.com". Having said all that, we will now confuse the issue by noting that the gateway machine for acci.com (that is, the machine that accepts all mail destined for the acci.com domain, and forwards it to the appropriate machines within that domain) can interpret *@*.acci.com any way it pleases, and in particular in ways that blur the distinction between domain and machine names. For instance, Tom Allebrandi, who lives on esther.acci.com, publishes his address as ta2@acci.com. Technically, acci.com is just a domain, administered by a particular organization (ACCI); ________ machines in that domain are esther.acci.com and marty.acci.com. But in "ta2@acci.com", "ta2" is an alias for the right mailbox within the acci.com domain. It matters not to the rest of the net whether that mailbox is on esther.acci.com or marty.acci.com; it is up to the domain gateway to get it delivered. Tom lives on __ esther, and esther happens to be the gateway, but it would still work if tom lived on marty, as long as the domain gateway knows how to reach "ta2". So the "host name" part -- "esther." or "marty." -- can be dropped out of the domain name in published addresses, for convenience. Small domains like acci tend to do it this way since the aliasing is easy (perhaps just a matter of entering one or two or a dozen VMS Mail forwarding commands). For a large domain, the aliasing can become a nightmare to administer, and so the domain REGISTERING AS AN INTERNET DOMAIN Page 9-12 Domain Names: Machines Vs. Companies administrator generally requires the full domain name and provides no intra-domain aliasing (except perhaps for those who live on or near the gateway node). For example, it is only due to administrative issues that you _ can't simply send mail to olsenk@dec.com. (Would you like the job of setting up an alias for everyone on the DEC's internal ___ network?) But you can send to user@decwrl.dec.com if user lives on any of the machines (not just decwrl) at DEC's Palo Alto facility; the facility is small enough that their postmaster can maintain aliasing tables for everyone who works there. 9.7 Special Acknowledgement Thanks to Bill Blue, Erik Fair, Glenn Sueyoshi, and Paul Vixie, whose articles and e-mail on these subjects contributed both to this chapter and to the "Address Formats" appendix. All mistakes, on the other hand, are our fault. CHAPTER 10 GETTING READY TO RUN NEWS At this point you have a working uucp mail machine, possibly known via an Internet domain-style address. You can now think about setting up news. Before proceeding, find the file [.DOC.NEWS_SETUP]NEWS.ANNOUNCE . This file contains the most recent (at the time this distribution was assembled) editions of articles that are posted monthly to the newsgroup news.announce.newusers. Print this file and read it before proceeding. (Once you have NEWS running, you can add the articles in this file to your news database, for benefit of your users.) 10.1 Newsgroups -- What To Carry? In setting up News and arranging for "news feeds" to and from other sites, you must decide which newsgroups you intend to carry on your machine. You probably do not want to accept everything that's available (the Usenet groups, listed in "List of Active Newsgroups" in NEWS.ANNOUNCE, plus all of the alternate hierarchies (see "describes the following alternate hierarchies", and there are others); this would total around four megabytes (soon to be five) a day, and a large percentage of it would be "noise". The following sections describe the small subset of newsgroups which all VMSnet sites should carry, and others which will likely prove valuable. 10.1.1 Strongly Recommended Newsgroups From The Usenet Hierarchy Although the term "Usenet" is commonly (loosely) used to refer to "all sites exchanging network news", technically there is a list of "official" Usenet newsgroups. This list appears in "List of Active Newsgroups". From this list, only the following are required for effective use of DECUS uucp: comp.mail... technically you only need comp.mail.maps (to keep your map files, and therefore PATHS., up to date), but GETTING READY TO RUN NEWS Page 10-2 Newsgroups -- What To Carry? at least some of the information in the other subgroups here will be useful to you, and the total volume is low. If you must keep things to a bare minimum eliminate .elm, .mh, and .sendmail . comp.os.vms this is in the "if you don't want this, why are you reading this?" category. ____ comp.org.decus same comment as preceding. Volume very low. news... nearly everything here is important. news.software.b, news.software.c, and news.software.notes can be eliminated, but volume is low enough in those groups that it isn't worth the bother. | | news.software.anu-news absolutely vital. The following group is quite optional, but has proved valuable: comp.sources.unix C programs for Unix A surprising percentage of these sources are usable under VMS (assuming you have the VAX C compiler). 10.1.2 The VMSnet Newsgroups Following established practice (cf. the gnu, alt, biz, etc., newsgroup hierarchies), we have established an alternate newsgroup hierarchy for discussion of VMSnet-related issues: Operational questions, bug reports and fixes, greetings from new sites, and so on. Initially, these will only be available from other DECUS uucp sites. We strongly encourage you, as a VMSnet site, to agree to feed these groups to other sites (both VMSnet and non-), if at all possible. At this writing, the VMSnet hierarchy consists of: | | vmsnet.admin administration of the VMSnet newsgroup | hierarchy | | vmsnet.announce general announcements of interest to | all VMSnet readers | | vmsnet.announce.newusers orientation info for new users | | vmsnet.mail discussions of e-mail on VMS systems, | other than via DECUS uucp GETTING READY TO RUN NEWS Page 10-3 Newsgroups -- What To Carry? | vmsnet.mail.pmdf gatewayed to info-pmdf | | vmsnet.misc general VMS topics not covered | elsewhere | | vmsnet.sources source code postings for VMS systems | (including uucp and ANU News-related | software) | | vmsnet.sources.d discussions and requests for same | | vmsnet.sources.games recreational software (optional) | | vmsnet.sysmgt VMS system management issues | | vmsnet.test for test postings | | vmsnet.uucp DECUS uucp and related software | (gatewayed to the vmsnet mailing list) 10.1.3 Others 10.1.3.1 Telebit Newsgroup If you are using a Telebit modem, you should carry the group "biz.telebit" . (The "biz" hierarchy was established to allow businesses to conduct exchanges which would violate the non-commercialism guidelines agreed to for the Usenet groups.) _________ Volume in the entire "biz" hierarchy is extremely low. 10.1.3.2 "to." Newsgroups By convention, News sites generally establish a newsgroup called "to.", for example to.simpact . These are only exchanged with neighboring sites, and are not "routed through" to neighbor's neighbors, and so on. Among other things, these groups are used for the exchange of "ihave/sendme" messages | (discussed later). Thus, you would have a "to.neighborname" | newsgroup for each neighbor with whom you exchange news. 10.1.3.3 Local Newsgroups It should not escape your notice that News can be a very effective tool for intra-company communication as well as communication with the existing world. You will probably want to create a hierarchy appropriate for your needs These newsgroups ___ should obviously not be fed to sites outside of your company. Their names are usually the company name or an abbreviation thereof. For example, we use simpact..., Hewlett-Packard uses hp..., and so on. GETTING READY TO RUN NEWS Page 10-4 Newsgroups -- What To Carry? 10.1.4 Decisions, Decisions Don't feel that you have to get all of this right the first time; everything can be changed and fine-tuned to your heart's content. So pick an initial set of newsgroups, realize that you'll make it better later on, and proceed. 10.2 Arranging For News Feeds Now that you have some idea of what newsgroups you want, you'll need to find somewhere to get them. At least one of your network neighbor system managers probably asked you "do you want News?" when you asked for a connection; your answer should have been "not yet". Now is the time to call them up and say, "Now I need news". All news sites are expected to maintain a username, or mail forwarding name, called "usenet". Mail sent there will be directed to the person responsible for maintaining the news software and data base on the machine. So, another method for finding a news feed is to send mail to !usenet, where is the name of each of your uucp neighbor sites (those named in [.CFG]SYSTEMS), to inquire about news feeds. However you contact them, tell them that you can send and receive News in "compressed rnews" format. This is the preferred method for transferring news in the uucp world. The compression/ decompression program, COMPRESS.EXE, is supplied in [.BIN]. (It is largely compatible with the LZCMP/LZDCM distributed through DECUS, but has some special features for handling compressed news.) Most well-connected uucp sites will carry the Usenet newsgroups listed above. (But they may not be willing to feed you, especially if you want a lot of newsgroups. A full news feed ties up a modem and considerable CPU resources for the "feeding" site. Your main news feed may not carry the newsgroups in the VMSnet | hierarchy. To find a feed for these groups, send mail to Terry | Poot, tp@mccall.com; he is coordinating the VMSnet sub-network. If none of your network neighbors carry the newsgroups you want, or if they can't feed you for some reason, ask them for suggestions as to where to get a feed. Or, inspect the map files for your region and look for sites that claim to be running News. You can also get news from PSI or uunet. (In fact, this is one of the primary main reasons that a lot of sites subscribe to a commercial service.) They are committed to carrying the entire Usenet hierarchy plus all "alternate" hierarchies, so if you like you can get all your news from them -- including the VMSnet newsgroups. GETTING READY TO RUN NEWS Page 10-5 Feeding News To Other Sites 10.3 Feeding News To Other Sites Obviously, if a majority of sites wanted only to receive news but didn't want to bother passing it on to anyone, the network would cease to function. At first VMSnet sites will, of necessity, be "end nodes" as far as the non-VMSnet newsgroups are concerned, but this condition should not last for long. If it does, we will be accused -- and rightly so -- of letting others pay the freight for our traffic. So, if you can provide a news feed to one or more of your uucp neighbors, we urge you to consider doing so. On the other hand, this is not a responsibility to be assumed lightly. Do not agree to provide a news feed unless you can be reasonably certain that you can continue to do so for the forseeable future; at the very least, if you must cut a site off from your news feed, you should try to give them a few weeks' warning. Also, if your system is down a lot, you don't want other people relying on you for news feeds. (An unreliable feed is worse than none at all!) This will be a non-problem for some time, since you won't be ______ well-enough known; nobody out there will be asking you for news feeds (other than other VMSnet sites, asking for the VMSnet newsgroups). 10.4 ANU News And DECUS Uucp Geoff Huston's News for VMS, referred to here and elsewhere as "ANU News" (for Australia National University News), or simply "News", is an implementation of Unix's "network news" functionality for VMS. The version of ANU News included with this distribution of DECUS uucp [1] is Version 6.0-2, as received from Geoff Huston. We have applied several bug fixes received from the net to the News source files and recompiled them. (These changes are described in [.NEWS60]FIXES.TXT .) DECUS uucp does include several programs, command procedures, and other files which integrate ANU News with uucp -- that is, they allow ANU News to exchange News with other sites (whether running ANU News, or Unix news implementations) via the uucp transport mechanism. Some of these are modifications of files supplied with ANU News, while others are our own invention. The latter are in directories other than those defined by Geoff. ____________________ [1] Note that while ANU News is included with DECUS uucp, it is ____ __ not part of DECUS uucp; we supply it for convenience. It isn't that we wouldn't be proud to have it under our umbrella; on the contrary, it deserves recognition and acclaim on its own. GETTING READY TO RUN NEWS Page 10-6 ANU News And DECUS Uucp We'll describe all of the files, the directory organization, and so on, in the next chapter. 10.5 News System Configurations An organization with a single VMS machine will run News in the simplest possible way, that is, with the News software and data base on that machine. But ANU News supports several more complex configurations. The following sections describe the possibilities. NOTE Just as we advised you to get your uucp links running for mail transfers before attempting to deal with News, we also advise you to get News running in "single-node" mode before making things more complicated. 10.5.1 VAXclusters A VAXcluster should be viewed as a "single News environment", with one copy of the News database on a disk visible to all cluster nodes (or at least all nodes from which users will be accessing it via the News user interface program). As usual for clusters, the logical names that define the News environment must be defined on each node in the cluster. If you are exchanging ___ News with either sites (by whatever means), one node in the cluster should be chosen to run the batch job that performs this function (described in full later on). By default this will be the same node in which uucp runs, but it doesn't have to be. Processing incoming and outgoing News can easily be done by another node in a VAXcluster, allowing better use of I/O bandwidth and CPU resources. 10.5.2 Independent News Machines Connected By DECnet If you have other VMS machines in remote locations, connected by low-speed (less than 56 Kbps) DECnet links, each of these machines would likely keep its own copy of News data base. Users would run the News software to interact with the data base on their local machine. Periodically (usually nightly), the News software on each machine will automatically forward (feed) News posted on each machine to all of the others, as directed by the configuration files. The transfers are normally performed during times when the systems and their DECnet links aren't in used for much else. GETTING READY TO RUN NEWS Page 10-7 News System Configurations 10.5.3 Independent News Machines Connected By Uucp Additional programs, command procedures, etc., provided with DECUS uucp allow the news to be forwarded via uucp as an alternative to DECnet. This is most probably how you will exchange News with existing "Usenet" sites. This is not an either-or decision; some systems can be fed via DECnet and others via uucp. 10.5.4 NNTP Via DECnet If you have other VMS machines nearby, connected to your "primary" News machine via high-speed DECnet links, you can use the "NNTP client/server" capabilities of news, and avoid keeping copies of the News database on each system. NNTP stands for Network News Transfer Protocol. Users on the other machines use the NNTP "client" program (supplied as part of ANU NEWS) to read and respond to the news; this program's user interface is exactly the same as if they were running News directly on their local machine. But instead of accessing a local News database, the NNTP client program uses DECnet to communicate with News "server" software running on the primary, accessing the News database remotely. Only the news articles that are actually read are moved across the network, and no articles are stored on the client machines. 10.5.5 NNTP Via TCP/IP You can also use NNTP if your server and client communicate via a TCP/IP network. This is probably irrelevant if all of the systems are VMS systems and have DECnet available. But if, for instance, you have a Unix system that can communicate with your VMS "news server" via TCP/IP, you need not arrange for news feeds to the Unix system; you can run NNTP news reader software on the Unix system, and it can obtain the articles to be displayed from the VMS server. 10.5.6 NNTP With Unix Server Conversely, if you already have a Unix system that's getting news, and if your VMS system can communicate with it via TCP/IP, you can run the ANU News client software on the VMS system and let it fetch news as required from the Unix-based NNTP news server software. The Unix NNTP server and client software are available from other sources (see the article, "Usenet Software: History and Sources"). GETTING READY TO RUN NEWS Page 10-8 News System Configurations 10.5.7 Variations You can also "mix and match" these options. A VMS NNTP News server can serve some clients via DECnet and others via TCP/IP, and also allow local users to access the data base directly, and also forward and accept nightly news database updates amongst remote machines in the organization. The one thing that probably does not make sense is to run the ___ NNTP News client and server software on the same machine, except for test purposes. 10.6 A Bit More About NNTP The difference between NNTP and doing batched nightly news transfers (whether via DECnet or uucp) is a little like the difference between copying a set of files from a remote system to your local system, editing one or two files on the local system, and copying the changed files back, and simply editing one or two files via remote file specifications on the edit commands (EDIT node::file...) . In both cases the editor itself is running on your local machine, and the user interface is the same. But in the former case the file transfer is all performed outside of the edit session, and the entire set of files is copied over as a unit and then copied back. In the latter case the data transfer is done within the edit session, and only those files actually being modified are transferred. 10.6.1 Why Do We Send More Stuff Over Slower Links? At first glance the options described -- NNTP over high-speed links, and transfer-all-new-news over low-speed links, seem backwards: If you're maintaining a complete news database on two different machines, and having them update each other each night, why would you do this over a low-speed connection? With a low-speed link, wouldn't it be better to just transfer the newsitems being read and written? The trouble is that you can't do that until someone runs the News client program, since until then you don't know what people want to see -- and the low-speed connection doesn't provide sufficient response time for interactive use (like editing a remote file when the DECnet link runs at just 9600 bps). 10.6.2 NNTP For Batched News Transfers Now, obviously, if a News client can use NNTP to ask a server for a particular news item (for display to the interactive user who's running the client software), an News system with its own data base could also use NNTP to ask a server for a news item (for updating its own news data base). Indeed, NNTP can be used for batched news transfers via a part of NNTP called "ihave/sendme". This part of NNTP can be used not only over DECnet and TCP/IP GETTING READY TO RUN NEWS Page 10-9 A Bit More About NNTP links, but uucp links as well. The idea is that the server sends the other system a list of news items that are eligible for transfer ("I have..."), and the other system sends back a (presumably smaller) list of the ones it wants ("Send me..."). In this way, a system that gets news from several sources can avoid receiving -- and paying for transmission time for -- multiple copies of the same item. (The multiple copies won't result in multiple appearances of the same item in the News data base, since News rejects incoming items whose Identification headers have already been seen, but they do take time to transfer; the intent of ihave/sendme is to reduce this redundant transmission time.) 10.6.3 Combinations News can be set up with some newsgroups kept locally and others "served", ie accessed on another machine via NNTP. 10.6.4 NNTP Warning We have no experience with NNTP Client/Server modes; all of the following assumes that you are setting up either a single-node News system, or multiple News systems with DECnet and uucp for standard (non ihave/sendme) batched file transfers. We hope to provide additional information on the NNTP Client/Server and ihave/sendme options in a future version of the documentation. CHAPTER 11 INSTALLING AND INTEGRATING NEWS This chapter will tell you how to set up the ANU News software and integrate it with uucp, so that you can exchange News with other sites. NOTE Before attempting to send or receive network news, you should have the uucp package running and properly exchanging mail with your neighbor sites. You can of course run News in "local mode", that is, without forwarding to or accepting from other sites, before you have accomplished this. 11.1 The ANU News Distribution If you obtain ANU News from another source it will come in "its own" directory tree, [NEWS60...]. (At least, that's how we got it!) If you get it with DECUS uucp, it's in [UUCP.NEWS60...] instead, mostly because it's more convenient for us to distribute a single directory tree. More details on the [.NEWS60] tree will follow. | | | 11.2 Documentation | | The news documentation as supplied by Geoff Huston appears in | [.NEWS60.NEWS_DOC]. It appears in several different formats, | most of them suitable for transfer to various microcomputer-based | word processing packages. A "plain Ascii" version is in | NEWSDOC.TXT . | | Before proceeding, print whatever form of the News User's Guide | (henceforth called the NUG) you can, read all chapters except | "NEWS Commands" thoroughly, and skim "NEWS Commands". (Relax; | "NEWS Commands" is the bulk of the document.) | | Some additional information appears in | [.NEWS60.NEWS_DOC]NEWSDOC.SUPP, and in text files in | [.NEWS60.NEWS_DIST]. The latter directory also contains samples INSTALLING AND INTEGRATING NEWS Page 11-2 | Documentation | for the News configuration files, which we will be editing in _____ ____ | later steps. Print out all files in this directory other than | NEWS.HLB . Do the same with the files in [.EXAMPLES.NEWS_MGR]. | Print them with /FLAG=ALL and /HEADER so that you can keep track | of which file is which. Review the text files and save the | others for reference in later steps. 11.3 Installing News: Comments On The News User's Guide You are now presumably ready and anxious to bring up News and see ____ how (and if!) it all works. (In our experience at least, it does work.) The last chapter in the NUG, "Installing News", provides some step-by-step instructions. The following subsections amount to "release notes" for this material, based on actual installation experiences. The idea is to read a section in the "Installing News" of the NUG, then read the corresponding section here before doing anything. The subsection headers below reference the names of the corresponding sections in the NUG. 11.3.1 Installing News Files This section of the NUG assumes you have received the news distribution as several different savesets. The instructions for restoring the various savesets into directories do not apply to the DECUS uucp distribution; this has already been done. 11.3.2 Compiling And Linking NEWS | NEWS 6.0-2, as supplied with DECUS uucp, was compiled and linked | under VMS Version 5.2, without support for any TCP/IP networking | package. You should not need to recompile it unless you need to | run under an earlier version of VMS or need to include TCP/IP | support. If you do want to rebuild it, you'll need the rest of the [.NEWS60...] tree out of the development saveset. Make whatever changes you wish to the source files, then submit [.NEWS60.NEWS_BUILD]NEWSBUILD.BAT to your favorite batch queue. | Read the comments in [.NEWS60.NEWS_BUILD]NEWSBUILD.COM to | determine the command procedure parameters required for the | TCP/IP package you are using, and pass these to NEWSBUILD.BAT . It will in turn invoke [.NEWS60.NEWS_SRC]NEWSBUILD.COM, which will only compile those objects dated earlier than their corresponding sources. (If you want to force a rebuild of the whole package, delete the object files and libraries from [.NEWS60.NEWS_BUILD] before starting the job.) (NEWSBUILD.BAT performs the SET DEFAULT command described in the NUG as being critical to the build procedure; in fact, that's the whole reason for NEWSBUILD.BAT's existence -- it doesn't matter INSTALLING AND INTEGRATING NEWS Page 11-3 Installing News: Comments On The News User's Guide what your default directory is when it's run. NEWSBUILD.BAT will also work fine interactively.) When the build is done, the new executables will be in [.NEWS60.NEWS_DIST], along with a new copy of NEWS.HLB. Inspect | NEWSBUILD.LOG to ensure that no errors occurred. (Be sure to | check for "undefined symbols" messages from the Linker; these are | reported only as warnings, but are almost always fatal if you try | to execute the resulting code.) When you're satisfied with the | results, you can delete the old .EXE and .HLB files that were | supplied with the distribution. | | | 11.3.3 NEWS Accounts | | The account created in this step will not be used by an actual | person (and, in fact, you can disable interactive logins for it). | Rather, it exists to provide an account under which the NEWSSKIM | batch job will run, and to provide a mail destination for News | items that are received as mail. (NEWSSKIM automatically "reads" | the mail directed to this account and imports it into News.) The | use of the term "News manager" in connection with this account is | somewhat misleading, as "manager" usually is a reference to a | real person, but in this case it refers only to an automatic | procedure. In order to avoid conflicts with the NUG, we will | continue to refer to this as the "News manager" account, but in | quotes, so you'll know that this "manager" isn't a person. | | To create this account, simply invoke the command procedure | [.BIN]UUCP_CONFIG , and choose option 4. As noted in the NUG, this account requires SYSPRV. In a cluster environment it will need NETMBX also. You can disable all but batch access for this account; its only purpose is to run the command procedure NEWSSKIM.COM in a self-repeating batch job. The default device and directory for this account should be the same as the translation of the logical name, NEWS_MANAGER (see the next step). The login command procedure should be NEWSMGR_LOGIN. The account should have a paging file quota (PGFLQUOTA) of at least 20,000 blocks. All tests with this software have used the VMS standard file protection (S:RWED,O:RWED,G:RE,W). Problems may occur if your system uses a different default. Insofar as the NEWSSKIM batch job is concerned, these problems may be obviated by placing the following command in NEWSMGR_LOGIN.COM : $ SET PROTECTION=(S:RWED,O:RWED,G:RE,W) INSTALLING AND INTEGRATING NEWS Page 11-4 Installing News: Comments On The News User's Guide 11.3.4 Define Logical Names The referenced file, SETUP_LOG_EXAMPLE.COM, does not appear in the current version of NEWS. For DECUS uucp, the functions of this command procedure are incorporated in another file, [.EXAMPLES.NEWS_MGR]NEWS_SYSTARTUP.COM . Edit NEWS_SYSTARTUP.COM as appropriate for your site. Following is a description of some of the logical names defined in this file. 11.3.4.1 NEWS_ROOT, NEWS_DEVICE These point to the root directory for the news database, in which all news items will be stored. The former is used to refer to files in the root directory itself, while the latter is a rooted directory specification, usable for looking at subdirectories. (Newsgroups are kept in subdirectories under this directory; for example, all articles in comp.os.vms will be stored in NEWS_DEVICE:[COMP.OS.VMS].) In the UUCP distribution, things are set up so that this directory is a subdirectory, [UUCP.NEWS], so that we would only have to distribute one root directory. As supplied, NEWS_SYSTARTUP.COM will correctly define these logicals if it finds either [NEWS] or [UUCP.NEWS] on UUCP_DISK. You can of course move [NEWS...] to another disk; just change the definitions of these logical names accordingly. Note that while it is perfectly okay to place [.NEWS] under another directory (as we have done here), the logicals NEWS_ROOT __ ____ and NEWS_DEVICE must not in turn be defined in terms of rooted directories! In other words, something like the following would ___ not work: $ defsysconc UUCP_DEVICE UUCP_DISK:[UUCP.] $ defsys NEWS_ROOT UUCP_DEVICE:[NEWS] $ defsysconc NEWS_DEVICE UUCP_DEVICE:[NEWS.] The same warning applies to the NEWS_MANAGER and NEWS_MANAGER_DEV logicals defined later. (Thanks to Rand P. Hall, who bumped into this problem and posted the explanation to the net.) 11.3.4.2 NEWS_MGR_UN equates to the username of the "News manager" account created in the preceding step. This is used in subsequent INIT/BATCH and SUBMIT commands. INSTALLING AND INTEGRATING NEWS Page 11-5 Installing News: Comments On The News User's Guide 11.3.4.3 NEWSMAIL, RNEWS These are the names of "mail drop" accounts which are used when sending News as mail. Mail sent to either of these usernames must be forwarded to the "News manager" username, defined by the logical NEWS_MGR_UN. You should not need to edit these commands. 11.3.4.4 NEWS_MGR_ID translates to an identifier name, which must be created and granted to the "News manager" account, and also to the accounts of any real people who are to be authorized to execute News management commands. The command procedure assumes that the identifier name is NEWSMANAGER, which is what the NUG describes. You can use something else as long as you change it consistently. [1] 11.3.4.5 NEWS_ADDRESS This should translate to the same name as UUCP_DOMAIN_NAME , and the supplied command procedure performs this translation automatically. It is used to generate "Reply-To" headers which are used for mail replies to posted articles. 11.3.4.6 NEWS_NODE ___ This is not (usually) the DECnet node name of the system (as described in the NUG), but rather the name by which this system will be referenced in the "Paths:" headers of news items posted or routed through the system. Most often, this should be the same as the system's uucp host name. It may also be a fully qualified domain name (in the form system.company.com). The supplied command procedure defines it to be the same as the uucp host name. 11.3.4.7 NEWS_MANAGER, NEWS_MANAGER_DEV These are analogous to NEWS_ROOT and NEWS_DEVICE, but they point to the directory in which the "news management" files are kept. These include a number of control files (to be created in a later step) and subdirectories which are used for forwarding news to ____________________ [1] If you are new to identifiers, you may well wonder why we can't use the identifier that's already associated with the "News manager" account (normally the same as its username). The answer is that an identifier that was created automatically as the result of the creation of an account, and which therefore translates to a UIC rather than to general identifier number, cannot be granted to other accounts. We have to create a separate identifier for the purpose; this will be done in a subsequent step. INSTALLING AND INTEGRATING NEWS Page 11-6 Installing News: Comments On The News User's Guide other nodes. Its functions are thus analogous to the combined functions of the [.CFG] and [.SPOOL] directories used by uucp. In the DECUS uucp distribution, this directory is a subdirectory, [UUCP.NEWS_MGR]. 11.3.4.8 NEWS_ORGANISATION This logical supplies the string which News places in the "Organization" header for locally-created news items. Set it to a (brief) exposition of your company name and location. (Users may override this with a process-level logical name.) 11.3.4.9 NEWS_BATCH_QUEUE translates to the name of a batch queue in which the "News manager" batch job, NEWSSKIM.COM, will run. NEWS_SYSTARTUP.COM will create the queue if it doesn't already exist. NOTE ____ This queue must be single-threaded; that is, its ____ /JOB_LIMIT must be one, and no more. If you use an existing queue, ensure that this requirement is met. 11.3.4.10 NEWS_BATCH_NODE On clustered systems, this logical defines which cluster node will execute the jobs in NEWS_BATCH_QUEUE. For nonclustered systems, this logical's equivalence name should be empty (""), as in the supplied file. 11.3.4.11 NEWS_EXECUTE_CONTROL translates to "Y" or "N". If "N", received control messages will be converted to command procedures and MAILed to the "USENET" account. If "Y", received control messages (to create and delete newsgroups, etc.) will be processed automatically, and confirmation notices will be MAILed to USENET. This is set to "N" in the distributed file; we recommend leaving it this way until you are comfortable with what News is doing. 11.3.4.12 NEWS_AUTO_CREGRP translates to "Y" or "N". If "N", received news items that are destined for newsgroups that don't exist on your machine will be placed in the newsgroup "junk". If "Y", the missing newsgroups will be created automatically. INSTALLING AND INTEGRATING NEWS Page 11-7 Installing News: Comments On The News User's Guide NOTE A hazard of automatically created newsgroups is that this mechanism has no way of knowing when to create the groups as moderated. If you use this, watch for incoming "cregrp" control messages and execute those which specify moderated groups. | | | 11.3.4.13 NEWS_TIMEZONE | | The three-letter abbreviation for the timezone in which your news | system runs. The supplied command procedure creates this | automatically, based on the uucp logical UUCP_TIME_ZONE. | | | 11.3.4.14 NEWS_GMT_OFFSET | | This logical provides the offset, in VMS time format, from | Coordinated Universal Time (UTC, formerly known as GMT) to your | local time zone. NEWS uses this value to convert the times in | news item headers (which are passed around the network in UTC | form) to local time. | | Time zones east of the International Date Line and west of | Greenwich, England (including those in the United States) have ________ | negative offsets, indicating that one subtracts the indicated | amount of time from UTC to get local time; time zones west of the ________ | International Date Line but east of Greenwich have positive | offsets. The supplied file provides the value "-8:00:00", which | is correct for United States Pacific Standard Time (PST). | | Remember to change this value when your area enters or leaves | Daylight Savings Time. 11.3.4.15 Other Logical Names Several other logicals, mostly associated with batch queues, are defined in NEWS_SYSTARTUP.COM . These are described in comments in the command procedure. 11.3.5 Create NEWS Logical Names This completes the customization of NEWS_SYSTARTUP.COM . You may now execute the procedure to define the logical names, e.g. $ @[.NEWS_MGR]NEWS_SYSTARTUP LOGICALS If you elect in a later step to change the locations of one of the directories, etc., simply edit this procedure to reflect the changes, then execute the new version to redefine the logical names. INSTALLING AND INTEGRATING NEWS Page 11-8 Installing News: Comments On The News User's Guide 11.3.6 Global DCL Symbols [.BIN]USERCMDS.COM defines the NEWS symbol as $ NEWS == "$NEWS_ROOT:NEWS" Edit your system-wide login command procedure to execute USERCMDS.COM for interactive logins, or otherwise make USERCMDS.COM available to those who will be using News. 11.3.7 Installing NEWS.EXE As A Known Image We will do this in a later step. 11.3.8 Initial Environment 11.3.8.1 Creating The NEWSMANAGER Identifier | The UUCP_CONFIG command procedure creates this identifier and | grants it to the NEWSMGR account when you create the account. | All that is necessary is to grant this identifier to your own | account, via the following command to AUTHORIZE: | | UAF> ADD/IDENTIFIER NEWSMANAGER | UAF> GRANT/IDENTIFIER NEWSMANAGER NEWSMGR | UAF> GRANT/IDENTIFIER NEWSMANAGER yourusername 11.3.8.2 Creating The Directories These directories, as named by the appropriate logicals, already exist under [UUCP]. DECUS uucp defines another special directory used for News-related log files. This is [.NEWS_LOG] in the DECUS uucp distribution. | | Use option 5 of [.BIN]UUCP_CONFIG to ensure that all file | ownerships and protections are set correctly for the NEWS | directories. 11.3.8.3 Setting Mail Forwarding For "USENET" You need to arrange for personal e-mail sent to the username "USENET" to be forwarded to the news manager. Note that "News ___ manager" in this step does not refer to the account created previously, but rather to the real person (probably you!) who will be responsible for creating and deleting newsgroups, approving control messages, and so on. The established convention on the net is for this person to be addressable as "USENET"; that is, if another site wants to send you a query such as "Do you carry rec.nude?", they will send it to usenet@yoursite unless they know your actual username. INSTALLING AND INTEGRATING NEWS Page 11-9 Installing News: Comments On The News User's Guide In addition, when "control" messages (such as create group, delete group, cancel newsitem, and so on) are received by News, its default behavior is to not execute them right away, but convert them into DCL command procedures and mail same to the USENET account. You are supposed to review them, pass judgement on them, and, if you deem appropriate, EXTRACT them and execute them. (You can also arrange for News to handle control messages without your supervision; in this case it will mail confirmation messages to USENET. See the description of the NEWS_EXECUTE_CONTROL logical name, preceding.) You can create an actual account called USENET, but you will then have to remember to log into it periodically to check up on pending work. Of course, this may be preferable to being bothered with control message execution requests in your regular VMS account! At any rate, if you choose not to create an actual USENET account, enter the following command to Mail: MAIL> SET FORWARD/USERNAME=USENET yourusername You can of course achieve the same result with a logical name assignment; we prefer to keep system-wide mail forwarding information in the VMSmail data base rather than in the system logical name table. 11.3.8.4 Copy NEWS.HLB To NEWS_ROOT This has already been done in the DECUS uucp distribution. 11.3.9 Installing NEWS.EXE NEWS.EXE already appears in the news root directory ([UUCP.NEWS]) in the DECUS uucp distribution. To install the image with the necessary privileges, use the command $ @[UUCP.NEWS_MGR]NEWS_SYSTARTUP INSTALLS 11.3.10 News Control Files In this step we create the control or configuration files used by News. The sample files provided with News 6.0-2 are in [.NEWS60.NEWS_DIST] . (You printed these out in an earlier step, remember?) Now is the time to examine them in detail. Read all of the comments carefully. (The text files use the Unix convention that a comment is a line beginning with a "#" in column 1, and continued lines are denoted with a trailing "\" on every line of the set except the last.) In a "live" news system all of these files reside in NEWS_MANAGER. [3] Accordingly, in the DECUS uucp distribution, there is a similar set of these files in [.EXAMPLES.NEWS_MGR]. INSTALLING AND INTEGRATING NEWS Page 11-10 Installing News: Comments On The News User's Guide The latter are the "live" files in use at Simpact at the time the distribution was put together. In general, you should build your configuration files based on the files in [.EXAMPLES.NEWS_MGR], not those in ____ [.NEWS60.NEWS_DIST] . It is a very good idea, though, to compare the two instances of each file to see what has been changed. The following sections will describe each file in detail. 11.3.10.1 NEWS.SYS This file establishes the incoming and outgoing news "filter sets", which determine which newsgroups your site will accept into its database, and which newsgroups your site will in turn forward to each of its neighbor sites. The first entry in both files is for the local node (though the entry for the local node need not be the first entry; the local node's entry is identified by the empty and fields (trailing "::"). The system name here (the field at the beginning of the entry) must be the same as that defined by the logical NEWS_NODE . The next entry in simpact's file specifies a dummy systemname, "mapsink", which is used for collecting the uucp map data. This tells News to copy all newly-arrived maps into the directory named in this entry; the NEWSSKIM batch job will find them and automatically update the mail routing data base ([.DATA]PATHS.). The directory name, [UUCP_MAPS], is "magic" and must not be changed. You can copy this entire entry from simpact's file. The next entries are for my various "news neighbors". Read the comments in the file to see why things are set up as they are. Each site should be explicitly enabled to receive the newsgroup "to.theirhostname", and in the entry for your system, you should enable the receipt of "to" (i.e. all "to.xxx" groups). There are several "distribution" newsgroup names shown in the supplied file: "world", "usa", "na" (for North America), "ca" (for California), and "ba" (for [San Francisco] "Bay area"). In most cases these do not correspond to actual newsgroup hierarchies, but correspond to things which will appear in the "Distribution:" headers of news items. News will reject incoming messages whose "Distribution:" headers specify something that does not appear in the node's filter set. This is used most often to limit the distribution of messages on a geographical basis. The current version of ANU News does not prompt for Distribution headers on outbound messages, but it does interpret them on incoming messages. Your prospective news feed sites ____________________ [3] In the NUG, NEWSSKIM.COM is described as residing in NEWS_ROOT. We have changed this in the DECUS uucp distribution. INSTALLING AND INTEGRATING NEWS Page 11-11 Installing News: Comments On The News User's Guide should be able to tell you the appropriate names to use here. For each entry that specifies news to be sent to another site (that is, all but the first, which is my entry), I need to specify the and fields. I'm not using ihave/sendme for anybody, so all of my are "B" (send in B News format). The specifies a directory and file name into which the outgoing news for the system in question will be written. This should always be NEWS_MANAGER_DEV/[POST_]NEWS.BATCH^B Where is normally the same as the system name at the head of the command, and dictates how the News will get there: o (empty), e.g. [POST_SITE1], means send via DECnet o "DECNET_", e.g. [POST_DECNET_SITE2], means send via DECnet (same as previous) o "UUCP_", e.g. [POST_UUCP_SITE3], means send uncompressed news via uucp to the "rnews" program on the target system o "UUCP$CMPRS_", e.g. [POST_UUCP$CMPRS_SITE4], means send __________ compressed news via uucp to the "rnews" program on the target system The latter is the method preferred by almost all existing Unix News sites. The filename, NEWS.BATCH, can be anything; NEWSSKIM looks for all files in the named directories. Note that for DECnet transfers, is used as a DECnet node name. For uucp transfers, it is used as a uucp hostname, and it must be a neighbor system -- that is, one that is named in [.CFG]SYSTEMS . For each to which you will be forwarding News, create these directories as subdirectories under NEWS_MANAGER_DEV. For example, for site esther, we did the following: $ CREATE/DIRE NEWS_MANAGER_DEV:[POST_UUCP$CMPRS_ESTHER] and similarly for all other sites to which we forward News. Finally, create the directory used by the map update mechanism: $ CREATE/DIRE NEWS_MANAGER_DEV:[UUCP_MAPS] Ensure that the "news manager" owns and has write access to all of these. INSTALLING AND INTEGRATING NEWS Page 11-12 Installing News: Comments On The News User's Guide 11.3.10.2 NEWS.DISTRIBUTION This file describes the topology of the News network from the point of view of your site, but only for your adjacent nodes. Its main purpose is to prevent "loops", ie the "reflection" of news from a site back to that site, which would cause no great harm (due to the message ids) but which would waste transmission bandwidth. Note that an entry is required for the mythical "mapsink" site, used for automatic processing of received map data. (See the description of the NEWS.SYS file above, and the comments in both files.) 11.3.10.3 NEWS.ALIASES Defines local aliases for newsgroup names. I have never seen much point to this, and indeed NEWS will run quite happily without it. 11.3.10.4 MAILPATHS. When someone on your site tries to post a message to a moderated newsgroup, News forwards the message to the moderator. (See Chapter 7 in the NUG, and also the article "List of Moderators" in NEWS.ANNOUNCE). Rather than requiring all sites to maintain an up-to-date list of moderators' addresses, the Usenet backbone sites have agreed to provide a "forwarding" service. The comments in the file explain the mechanism further. In almost all cases, VMSnet sites will need but a single entry in this file, specifying "backbone". The target address is the address of your "nearest" backbone site (nearest in terms of the mail network topology, which is not necessarily the same as geographical nearness). Unless a site name jumps out at you as the obvious choice, you will have to inspect the map files to find out where these various sites are and where they are likely to be in relation to yours. 11.3.10.5 NEWSSKIM.COM This is the command procedure that runs as a batch job under the "News manager"'s account. NOTE The DECUS uucp version of NEWSSKIM.COM (in [.EXAMPLES.NEWS_MGR]) is substantially different ______ from that in [.NEWS60.NEWS_DIST]; ignore the latter version and use ours. INSTALLING AND INTEGRATING NEWS Page 11-13 Installing News: Comments On The News User's Guide Inspect this file and make alterations as follows: o If you want to alter the batch job's run frequency and time limits, edit the code near the end of the file, under the label "abort:". o Inspect the available qualifiers on the "Add Batch" commands to see if you wish to add or delete any. (See the description of the "Add File" command in the NUG, Section 6.3; "Add Batch" is a synonym for "Add File".) | | o There is a set of commands that establishes the news | item retention periods for newsgroups based on whether | or not there are local readers. You should review these | and edit them as appropriate for your site. Place the resulting file in [UUCP.NEWS_MGR]. 11.3.10.6 NEWSSKIM_LOGICALS.COM This file is invoked by NEWSSKIM.COM to define logical names which affect NEWSSKIM's behavior. At present it is used only to define logical names for mail forwarding used in either mail-based news feeds or in gatewaying newsgroups to mailing lists. If you aren't doing either of these, ignore this file (ie you don't need a version of it in [.NEWS_MGR]). 11.3.10.7 NEWS_ADDRESS.CNF This file allows News users to easily send Mail, possibly through DECnet, uucp, or other transport mechanisms, to the authors of news articles. It specifies how author's addresses, as shown in "From: " headers in news items, are to be translated so that they are acceptable to VMS Mail. ANU uses PMDF for its Internet mail, so its address translation rules specify "IN%..." (IN% is PMDF's equivalent to our UUCP%). Simpact uses uucp for Internet mail, so our address translation rules specify the now-familiar UUCP% for anything we can't send locally. | | Note that earlier versions (5.7 and earlier) of ANU NEWS needed | bunches more quotes (") in the entries in this file. For | example, where we used to say | *@* "UUCP%""001@002""" | | we now say | *@* UUCP%"001@002" | | If you are converting from 5.7 or an earlier version of News, be | sure to change this file accordingly. INSTALLING AND INTEGRATING NEWS Page 11-14 Installing News: Comments On The News User's Guide | 11.3.10.8 NEWS_POST.DEFAULTS | | Read the comments. The purpose of this file is to force the | "Distribution:" and "Followup-To:" headers in items posted to | specified newsgroup to specified values. For example, this might | be used to ensure that local newsgroups stay local (by | constraining the "Distribution:" header). | | | 11.3.10.9 NEWS_POST.CC | | This file associates unmoderated newsgroups which happen to be | gatewayed with mailing lists, with those mailing lists. Leave | this file empty unless you are serving as the gateway for such a | list. | | | 11.3.10.10 Other Files | | Several other files are supplied in [.NEWS60.DIST]: | | o DCLNEWS.HLP is a help module for insertion in a | site-specific extension to HELPLIB.HLB (or into | HELPLIB.HLB itself, if you are so inclined). While | NEWS_ROOT:NEWS.HLB provides the help that is available | within News, this file provides information on the News | DCL command, available by typing "HELP NEWS" at the DCL | prompt. If you use this file, be sure to customize it | for your site. | | o NEWSEDIT_EXAMPLE.COM is a template for a command | procedure which would allow a user to specify a | non-standard editor for the creation of News items. | (The standard editors available are TPU and Callable | EDT.) See the description of the logical name, | NEWS_EDIT, in the NUG. This file should be placed in a | public directory and made world readable. | | o NNTP_FEED.COM is used to forward News to other sites via | the NNTP protocol, via DECnet, CMU TCP/IP, or WIN | TCP/IP. | | o The functions of the following files are incorporated in | DECUS uucp's version of NEWSSKIM.COM. Accordingly, | these files may be ignored: | | NEWSADD.COM NEWSDAILY.COM | NEWSPACK.COM NEWSSKIM_ALT.COM: | | | 11.3.11 First Time Execution Of News | INSTALLING AND INTEGRATING NEWS Page 11-15 Installing News: Comments On The News User's Guide | 11.3.11.1 Startup | | Double check everything, then from an account with SYSPRV, enter: | | $ @UUCP_BIN:USERCMDS | $ NEWS | | NEWS will respond with | | NEWS - create new ITEM file | NEWS - first time installation... | VMS NEWS V6.0 - LICENSE | | and then sit there. | ____ _ ________ ______ | Type a carriage return to display the first screen of the license | form; continue hitting return to display the rest. | | This form is also placed in the file | NEWS_MGR:000README.NEWS_LICENSE . Please print it, fill it out, | and mail it to Geoff, or edit it, fill it out, and send it to him | via electronic mail. | | After a final to continue, NEWS will say | | NEWS - create new GROUP file | | and will then place you in a newsgroup directory screen, with no | newsgroups visible (since none have been created). | | NOTE | ___ | Do not exit News at this point without creating | at least one newsgroup! (See the next section.) | If you do it will leave your "NEWSRC" file in an | incorrect state, causing News to abort with an | access violation on subsequent attempts to run _ | it. If you make this mistake (guess how I know | about this!), delete NEWS_ROOT:NEWS*.V50 and | SYS$LOGIN:NEWSRC., and start again. | | | | 11.3.11.2 Creating "control", "local", And "junk" | Enter the following commands at the NEWS> prompt: create group control create group local | create group junk After each command it will respond with "Create Newsgroup? [n]:". Enter "Y" followed by a return to confirm. After creating these two groups, enter the EXIT command (or a Ctrl-Z) to exit News. INSTALLING AND INTEGRATING NEWS Page 11-16 Installing News: Comments On The News User's Guide 11.3.11.3 Creating The Initial Newsgroup Set At this point you need to tell News about the newsgroups you have decided to accept from various sources. In [.DOC.NEWS_SETUP] there is a file, CHECKGROUPS., which is a copy of the most recent "checkgroups" postings as of this | writing. (In fact, this file is getting a bit old, but it's the | latest one we've received.) What you want to do is produce a file in this same format which reflects only those newsgroups you want to carry. Edit the CHECKGROUPS file to create MYGROUPS.TXT, as directed in the opening remarks (delete the first "=========" line and everything before it, and delete the last "=========" line and everything after it; this will leave you with Newsgroups: news.admin.ctl,control Distribution: local Approved: spaf@cs.purdue.edu Subject: cmsg checkgroups Control: checkgroups !mod comp.ai Artificial intelligence discussions. comp.ai.shells Artificial intelligence applied to shells. (Moderated) . . . talk.rumors For the posting of rumors. Note that the blank line between the "Control: checkgroups" and the first line of the newsgroup list must be present. Now edit what's left to eliminate all the groups you don't want. Append to MYGROUPS.TXT descriptions of all of the VMSnet groups (you can find these, listed in the correct format, in CHECKGROUPS.VMSNET). If you are interested in any of the groups in the "alternate" hierarchies, edit the file NEWS.ANNOUNCE, find the "Alternative Newsgroup Hierarchies" article, and append to MYGROUPS.TXT the descriptions of the groups you want. Finally, add a line to MYGROUPS.TXT that says to.myhostname messages from neighbors When you are satisfied with your first version of MYGROUPS.TXT, you can invoke NEWS again, and at the NEWS prompt type: NEWS> ADD FILE MYGROUPS.TXT INSTALLING AND INTEGRATING NEWS Page 11-17 Installing News: Comments On The News User's Guide A few messages will appear, and you will get two Mail messages (assuming that you are to whom messages sent to USENET are forwarded). Exit News, enter Mail, and EXTRACT/NOHEADER the first of these into a disk file (perhaps MYGROUPS.COM). Exit from Mail and, from the DCL prompt, execute this file as a command procedure, e.g. $ @MYGROUPS.COM This will create the newsgroups you have requested. NEWS is now ready to accept these newsgroups from your news feeds. Assuming that you have included the newsgroup news.announce.newusers, you can again invoke NEWS and _ NEWS> ADD FILE [UUCP.DOC.NEWSSETUP]NEWS.ANNOUNCE This will add the articles contained in the file to the newsgroup. By default, groups are created with a default item retention | period of thirty days. You can modify the default for all | groups, and you can also modify the retention period for | particular groups, with the SET NEWSGROUP command; see the NEWS | documentation. | | The NEWSSKIM batch job, as supplied with DECUS uucp (in | [.EXAMPLES.NEWS_MGR], will automatically modify the retention | period of newsgroups based on whether or not anybody at your site | has subscribed to them. Local overrides are provided for. | Review the relevant portions of NEWSSKIM.COM and make changes as | appropriate for your site. You will probably want to set the retention period for comp.mail.maps down to one day. All newly-arrived maps are copied into the UUCP_DATA_MAPSRC directory within a day, where they remain until replaced by later versions of the same maps. Since the maps are updated on a monthly basis, the default retention period will cause you to retain two complete copies of the map data -- at least one of them uncompressed! -- which is a needless waste of space. The final step is to ensure that incoming news batches get routed to News, and that News can properly forward to the sites you feed, whether via DECnet or uucp. This is covered in the following sections. 11.4 Exchanging News With Other Sites (Batch Transfers) INSTALLING AND INTEGRATING NEWS Page 11-18 Exchanging News With Other Sites (Batch Transfers) 11.4.1 DECnet Transfers The method used for DECnet transfers is as follows: o When news items are posted, News uses the NEWS.SYS file to determine which, if any, systems the newsgroups in question are forwarded to. It then creates files containing the items to be forwarded in the directory named in each system's entry in NEWS.SYS. The format of the directory name in the NEWS.SYS entry specifies that the transfer is to be via DECnet. o The NEWSSKIM command procedure, which runs periodically as a batch job under the "News manager" account, looks for these files and copies them (using ordinary DECnet file copy) to the corresponding DECnet node. o The NEWSSKIM command procedure on the target node, running periodically, looks for these received files in the NEWS_MANAGER directory. When it finds them, it adds them to the news data base. (Of course, in most environments, the two systems will exchange news in both directions. NEWSSKIM always looks ___ for incoming news and sends outbound news.) For this to work, the following conditions must be met: o News must be set up as described here on all machines in the network. o DECnet default proxy login entries must exist for the "News manager" account on all systems, so that the DECnet file copy goes to the "News manager"'s default directory on the target system, and so that the copied files are owned by the correct account. o The default device and directory of the "News manager" account on each node must point to the same directory as the logical name, NEWS_MANAGER. o Appropriate entries must exist in the NEWS.SYS file to specify transfer via DECnet, and the subdirectories named in those entries must exist under NEWS_MANAGER. o If news received from other sites is to be sent to the DECnet node, appropriate entry(ies) must exist in NEWS.DISTRIBUTION . o The NEWSSKIM batch job must run periodically on all machines. INSTALLING AND INTEGRATING NEWS Page 11-19 Exchanging News With Other Sites (Batch Transfers) 11.4.2 UUCP Transfers (both To Unix And To VMS) Ignore the relevant section in the NUG; very few Unix sites are happy to deal with Mail-based News feeds, and since the DECUS uucp distribution supports the more desirable "compressed rnews" mechanism, there is no need for them to do so. Uucp news transfers work as follows: o When news items are posted, News uses the NEWS.SYS file to determine which, if any, systems the newsgroups in question are forwarded to. It then creates files containing the items to be forwarded in the directory named in each system's entry in NEWS.SYS. The format of the directory name in this case specifies that the transfer is to be via uucp, and whether or not the files are to be compressed before transmission. o The NEWSSKIM command procedure, which runs periodically as a batch job under the "News manager" account, looks for these files, compresses them if necessary, and invokes the "uux_rnews" program for each. o Uux_rnews creates the necessary files in the uucp spool directory so that, during the next uucp call to or from the neighbor system, the news batch file and an "execution" file will be transferred. o Upon receipt of the "execution" file, the receiving system passes the received news batch file to the "rnews" program. Under DECUS uucp, rnews is a command procedure, UUCP_BIN:NEWS_RNEWS.COM, which is run in the NEWS_BATCH queue by UUXQT_DCL. o For incoming news, the neighbor system places in the uucp spool directory a D.xxx file containing the (possibly compressed) news batch, and an X.xxx file containing instructions for processing the D.xxx file. Upon receipt of the X.xxx file, the uucico program awakens the uuxqt image, which passes the X.xxx file to the uuxqt DCL subprocess. This in turn submits a batch job, NEWS_RNEWS.COM, in the News batch queue. This job (finally!) runs the compress utility (in decompress mode), if required, and then invokes NEWS to ADD the contents of the file to the News database. Finally, all intermediate work files are deleted. For this to work, the following conditions must be met: o News must be set up as described here on all of the VMS machines in the network. o Appropriate entries must exist in the NEWS.SYS file to specify transfer using (probably compressed) uucp, and the corresponding subdirectories must exist under NEWS_MANAGER. INSTALLING AND INTEGRATING NEWS Page 11-20 Exchanging News With Other Sites (Batch Transfers) o If news received from other sites is to be sent to the uucp host, appropriate entry(ies) must exist in NEWS.DISTRIBUTION . o The NEWSSKIM batch job must run periodically. o You must have a uucp connection to each of the systems you're sending news to (as described in NEWS.SYS). 11.4.3 Ihave/Sendme Transfers Via UUCP Or DECnet (This will not be used by most sites.) This is similar to the setup for standard uucp or DECnet transfers. Make the following changes in NEWS.SYS for each system to which News will be forwarded using ihave/sendme: o Change the third field in the system's entry (the field; a single character, with colons on either side) from "B" ("B" news format) to "N" (NNTP ihave/sendme). o Depending on the capabilities of each system, you may ____ need to change the last character in the system's entry -- the article format -- from "B" (for batched transfer; all articles to be transferred to one system go in a single file) to "M" (for multiple, meaning that each article goes in a separate file). Changing the field causes News, when collecting News for transfer to the other system, to merely build a list of article ids in the transfer file (or files, if the article format is "M"). This list is sent to the other system as an "ihave" control message. The other system examines the list and sends back a "sendme" control message; News on your machine responds by queueing for transfer the articles listed in the "sendme" (usually during a later call). The intended result is less transmission time but greater transfer latency. 11.4.4 Feeding News Via NNTP We have no experience with this; refer to the NUG. There is a faint possibility that one of our changes to NEWSSKIM.COM, or other procedures, may have "broken" the instructions provided for NNTP News feeds. We would appreciate hearing from anybody who gets this running. 11.4.5 Receiving A News Feed Via NNTP This must be possible, but I don't quite see how to set it up. If a News_server is running, would it accept News feeds via NNTP? INSTALLING AND INTEGRATING NEWS Page 11-21 NNTP Client/Server Support 11.5 NNTP Client/Server Support Again, we have no experience with NNTP; refer to the NUG. Anyone who sets up News in NNTP Client or NNTP Server mode, or who uses NNTP news feeds, is urged to keep a log of what you do while you're setting it up. Send it to both Geoff Huston and the VMSnet Working Group, so that we can enhance future versions of the documentation (with credit, of course!). 11.6 Start Up The Transfer Processes Submit the NEWSSKIM batch job for periodic execution. You can do this by invoking the startup procedure as follows: $ @NEWS_MANAGER:NEWS_SYSTARTUP BATCH_JOBS When you are satisfied that all is well, edit the command in your system startup command procedure that invokes UUCP_SYSTARTUP to include a P2 parameter, as follows: $ @ddcu:[UUCP.BIN]UUCP_SYSTARTUP "" INCLUDE_NEWS This will cause UUCP_SYSTARTUP to invoke NEWS_SYSTARTUP at the appropriate time in the startup sequence, that is, after all of the UUCP_ logicals have been defined, but before any of uucp's batch jobs are started. (NEWSSKIM might fail if it tries to run before the UUCP_ logicals exist, and the uuxqt batch job might fail if it tries to run before the NEWS_ logicals exist.) APPENDIX A USING TELEBIT MODEMS The Telebit Trailblazer Plus, Telebit 2500, and similar modems have become a de facto standard for high-speed links in the uucp world. Besides their "ordinary" high speed and error correcting capabilities, they offer a "spoofing" mode for the uucp "g" protocol, wherein the modem speaks the uucp protocol to the local system but runs its own error-correcting protocol over the telephone link. This provides much better throughput than would be possible with a standard high-speed modem, since it eliminates the necessity to move uucp's error-protection data over the wire, and also allows for more-rapid acknowledgements of transmitted packets to the sending system. Uunet gets 11,000 bits per second throughput with Telebits "on real data under real conditions" (according to Uunet's information packet); in tests between DECUS uucp systems with quiet lines we regularly achieve 12,000 bps, and often reach 14,000. In short, these modems can provide a real cost savings over 2400 bps modems if you move a lot of data over long-distance lines. This Appendix describes how to use the Telebit Trailblazer Plus and T2500 modems with DECUS uucp. [1] We have no direct experience with other Telebit models. (We really don't mean to sound as though we're putting in a plug for Telebit's modems; we have no connection with the company ____ other than as very satisfied customers.) A.1 Serial Port Requirements The setup to be described assumes that the VAX serial port to be used implements modem control signals, as described in the chapter on "Modems and Multiplexers". | | If you will be using the Telebit for ordinary interactive dialin, | the port must support the Clear To Send signal. Such ports | include: ____________________ [1] This material is based very closely on an article Mark Pizzolato wrote for posting to netnews, earlier this year. USING TELEBIT MODEMS Page A-2 Serial Port Requirements | o All ports in the DHV11, DHQ11, DHU11, DMB32, DMZ32, | CXY08 | | o Ports 0 and 1 on the DMF32 | | o The DB25 serial port on the MicroVAX 2000 | | o All ports on a DECserver 200MC | | Ports which implement partial modem control (such as those on the | DZ family) may be used with a Telebit modem for uucp, but not for | interactive dialin. Ports on the CXA16, CXB16, and ports 2 through 7 on the DMF32, provide no modem control signals. Telebits will not work as described below with these ports. (This doesn't mean that they won't work at all, only that you'll have to live with the security problems that exist when the VAX can't make the modem hang up the line.) A.2 Goals We have several seemingly contradictory requirements. We want: o To be able to initiate uucp outbound calls at a speed appropriate for the modem being called; o To have the default outbound speed on the line be 19200 when using "SET HOST/DTE" and/or asynchronous DECnet, since dynamic speed select is not normally possible with "SET HOST/DTE"; o To allow callers to dial in at a speed appropriate for the modem they were using and dynamically autobaud to their speed; and o To be able to call some Telebits that answer with PEP tones last, but still establish a PEP connection. The solution is to use a locked interface speed (at 19,200 bps) | for both incoming and outgoing calls, allowing the modem to connect at the speed of the other modem and take care of the speed difference between that and the VAX. Running the phone line at a lower speed than the interface to the VAX (for incoming calls) raises the possibility that the VAX could send data faster than the modem could send it down the | line. This is not a problem for uucp connections (either to | other Telebits or to ordinary low-speed modems) because the uucp __ | protocol includes its own flow control. It is a problem for | interactive users. We take care of this by using hardware flow control (using the CTS signal), if available, to throttle data going from the VAX to the modem. No flow control is needed in the other direction (modem to VAX) because we're going the "other way" -- from a lower-speed line to a higher-speed line. USING TELEBIT MODEMS Page A-3 Goals We also need to comply with the other requirements detailed in the chapter on "Modems and Multiplexers", but this is not difficult with the Telebit modems. A.3 Modem Settings Here are the settings that are different from the factory defaults. These are described for the Telebit TrailBlazer Plus and for the T2500. If you have another type of Telebit modem, you'll have to read the manual and see for yourself how applicable these are. o E0 Don't echo commands from host o Q6 Return result codes only on outgoing calls. o X3 MNP & PEP extended result codes enabled. | | o &T5 Deny test requests from the remote modem. | (T2500 only) o S7=90 Specify 90-second wait for carrier. | | o S51=5 Set host interface speed to 19200. o S52=2 Hang up and reset to EEPROM values on DTR drop. o S53=2 DSR ON only when DCD is ON. DCD is ON when carrier is detected. (TrailBlazer Plus only) o S54=3 Pass BREAKs transparently. o S58=0 No flow control is used to control the flow of data coming from the modem to the host (since the host can take data at 19200, faster than the modem can possibly send it, no flow control is needed). o S66=1 Lock interface speed and enable flow control. o S68=2 Use hardware flow control from modem to host: The modem turns CTS off when its buffer for outgoing data is full, and on when the modem can accept more data. o S92=1 Issue the PEP answer tones at the end of the search sequence rather than at the beginning to accommodate connecting with slower speed (non-PEP) modems. | | o S110=0 Data compression is disabled. (The bulk of | our traffic will be news, which is already compressed.) USING TELEBIT MODEMS Page A-4 Modem Settings | o S130=5 DSR follows CD. (T2500 only) | | o S131=1 CD is ON when carrier is detected. (T2500 | only) A.4 Setting It Up Here's the full procedure for getting a brand-new Telebit working with your VAX under DECUS uucp. We assume that it's connected to a port named TXA0:. 1. Set up the port attributes somewhere in the system startup files with the following command: $ SET TERMINAL TXA0: /PERMANENT/SPEED=19200 - ! needed /MODEM/HANGUP/DIALUP/TYPEAHEAD/ALTYPEAHD - ! needed /DMA/SYSPASSWORD/TTSYNC/HOSTSYNC ! optional Note the explicit setting of /SPEED vs. /AUTOBAUD. See Chapter 4 for information about the optional attributes. We recommend /DMA, /TTSYNC, and /HOSTSYNC; /SYSPASSWORD is up to you. ___ We do not recommend trying to use a Telebit without using the alternate typeahead buffer; further, the _ __ _____ SYSGEN parameter TTYALTYPAHDSZ should be set to at least 210 (up from its default of 200). [2] | | 2. The following instructions assume that the modem's | starting configuration is that with which the modem is | shipped from the factory. If the modem's default | power-up configuration has been changed, refer to the | modem's instruction manual to restore it to the factory | settings. (See, for example, pages 6 and 7 in the _______ _____ ____ _____ _____ | Telebit T2500 Fast Start Guide.) | | 3. If you have a T2500, or other model with "A/B" and "T/D" | switches on the front panel, the "A/B" switch selects | one of two non-volatile memories for user-modified | parameters. This switch may be set to either position, | but whatever position the switch is in when the modem is ____________________ [2] As noted in the chapter on modems and terminal multiplexers, A typeahead buffer size of 210 will be sufficient for uucp. Larger values may be appropriate if you intend to use the Telebit for "normal" interactive logins to other computers with Telebits. The Telebit's data compression capability, along with latencies in common terminal emulation software (including KERMIT and SET HOST/DTE), can result in the modem sending large bursts of data faster than the software is capable of emptying the typeahead buffer. Larger values (approximately 2000 for one screen's worth) may help avoid data overrun conditions in these cases. USING TELEBIT MODEMS Page A-5 Setting It Up | configured as described below, the switch must remain in | that position for subsequent use by uucp. 4. Connect to the modem using: $ ALLOCATE TXA0: $ SET TERMINAL/SPEED=19200 $ SET HOST/DTE TXA0: and then type the following: AT (the modem should respond with "OK". If not, try typing AT a few more times.) (for the TrailBlazer Plus) AT &F Q6 X3 S7=90 S52=2 S54=3 S58=0 S68=2 AT E0 S51=5 S66=1 S92=1 S110=0 S53=2 &W (for the T2500) AT &F Q6 X3 S7=90 S52=2 S54=3 S58=0 S68=2 AT E0 S51=5 S66=1 S92=1 S110=0 S130=5 S131=1 &T5 &W The of course represents a carriage return. Note that you may need to hit "A" several times at the beginning of the line before the modem autobauds and echoes an "A". The above command will cause DSR & DCD to drop, so "SET HOST/DTE" might exit immediately. This is all right, but to be sure that things worked right, "SET HOST/DTE" again and use AT &N to display the modem's settings. 5. Exit back to DCL with ^\ (that is, Ctrl-Backslash) and release the modem port: $ DEALLOCATE TXA0: A.5 Control And Systems File Entries The supplied file [.CFG]CONTROL. shows such a modem on TXA0: | port ACU hayes txa0: 2400 L | port ACU tbgspoof txa0: 19200 L This says that systems entries specifying "ACU" and "2400" will use the normal Hayes dial script, but those specifying "ACU" and "19200" will use the special "tbgspoof" script, which enables "g" protocol spoofing. Naturally, the 19200 speed should only appear in systems entries with phone numbers to which Telebit modems are USING TELEBIT MODEMS Page A-6 Control And Systems File Entries connected! | | The trailing "L" (may be upper or lower case) tells DECUS uucp to | not change the port speed on outbound calls. In this case the | speed in the port entry simply tells DECUS uucp which speeds the | modem is capable of using. These modems will correctly connect | to modems of various speeds and perform speed conversion between | the line and the VAX. | | | A.6 Communicating With Other Telebits | | Ensure that other sites which call you with Telebit modems give | their modem an S50=255 command before dialing your number. This | assures that a PEP connection will be made even though your modem | answers with the PEP tones last. A.7 Compatibility Issues (old History) While debugging this, Mark Pizzolato found a bug in Telebit's implementation of the "g" protocol. At the time, we were still using the non-windowed "g" protocol implementation from the original gnuucp, and this used a feature of the protocol that neither HoneyDanBer or other Unix uucp implementations seem to use. Since Telebit had never seen it used, they didn't provide for it. Telebit will have a fix, but since it only affects the VMSnet Version 0.1 and 0.2 distributions, and DECUS uucp 1.0 does ___ not use the feature, you need not worry as to whether or not your modem is upgraded. For the curious only: The problem was that, in certain cases, piggybacked ACKs weren't being handled correctly by the modem, and the modem would hang. Piggybacked ACKs are a mechanism whereby the acknowledgement of data message in one direction rides "piggy back" in the control portion of a data message going in the other direction. The "g" protocol allows this, but since Telebits have been such a success, and this problem hasn't come up before, gnuucp's "g" protocol implementation must at least be using this in a way that the Unix implementations don't. In Version 1.0 of DECUS uucp, we always ensure that all pending ACKs are sent before sending any data messages, and so we never send a "piggybacked ACK" if we haven't already sent the corresponding data message. Piggybacked ACKs can be a real win if you have large amounts of data moving in both directions on a line at the same time, but since the "upper layers" of uucp only use the link in a half-duplex manner (at any given time, one file is being moved in one direction; it cannot overlap file copy in and copy out operations), elimination of piggybacked ACKs costs nothing in terms of performance. USING TELEBIT MODEMS Page A-7 Compatibility Issues (old History) Many, many thanks to Mike Ballard at Telebit for his support while isolating the "g" protocol bug and debugging changes to gnuucp's gio module to accommodate the modem. -- MP APPENDIX B PATHALIAS (UUCP MAP FILE FORMAT DETAILS) The following material is adapted from the "manual page" for Unix pathalias(1), written by Dr. Peter Honeyman. B.1 Description The command procedure [.BIN]MAKEPATHS.COM generates the file [.PATHS], which reflects the shortest paths and corresponding routes from one host (computer system) to all other known, reachable hosts. Most of the work is performed by the program _________ pathalias. Pathalias reads host-to-host connectivity information from the uucp map files in [.DATA.MAPSRC], and writes a list of host-route pairs on the standard output. B.2 Uucp Map File Format A line beginning with white space continues the preceding line. Anything following "#" on an input line is ignored. A large number of conventions for "#"-lines is recommended for map entries (see the file [.DATA.MAPSRC]README.); these lines are important to the people who maintain the map database, but are ignored by pathalias. Pathalias's primary input consists of lists of host-to-host ____ connections. Such a list of connections consists of a from host in column 1, followed by white space, followed by a _____ comma-separated list of "to" hosts, called links. B.2.1 Uucp Mapping Project Requirements In entries published in the uucp maps, host and domain names may contain the following characters: "a" through "z", "0" through "9", and "-" (dash). Fully qualified domain names may contain "." (dot). No other characters, including uppercase alphabetics and underscore will be accepted anywhere in the name. In addition, host names and each section of the domain name must ___ begin with a lowercase alphabetic and may not end with a dash. PATHALIAS (UUCP MAP FILE FORMAT DETAILS) Page B-2 Uucp Map File Format The above applies to all names given on the #N and #F lines as well as all names that appear in the link description portion of ___ your map entry. It does not apply to pseudo network names used to help describe internal networks, as defined below. B.2.2 Network Characters A link may be preceded or followed by a network character to use in the route. Valid network characters are "!" (default), "@", ":", and "%". NOTE The uucp mapping project will not accept map entries with network characters other than "!" (which is the default anyway, so why bother). B.2.3 Costs A link (and network character, if present) should usually be followed by a "cost" enclosed in parentheses. Costs may be arbitrary arithmetic expressions involving numbers, parentheses, "+", "-", "*", and "/". The following symbolic costs are recognized: LOCAL 25 (local-area network connection) DEDICATED 95 (high speed dedicated link) DIRECT 200 (toll-free call) DEMAND 300 (long-distance call) HOURLY 500 (hourly poll) EVENING 1800 (time restricted call) DAILY 5000 (daily poll, also called POLLED) WEEKLY 30000 (irregular poll) In addition, DEAD is a very large number (effectively infinite), HIGH and LOW are -5 and +5 respectively, for baud-rate or quality bonuses/penalties, and FAST is -80, for adjusting costs of links that use high-speed (9.6 Kbaud or more) modems. These symbolic costs represent an imperfect measure of bandwidth, monetary cost, and frequency of connections. For most mail traffic, it is important to minimize the number of hosts in a route. So, for example, HOURLY * 24 is much larger than DAILY. If no cost is given, a default of 4000 is used. For the most part, arithmetic expressions that mix symbolic constants other than HIGH, LOW, and FAST make no sense. For example, if a host calls a local neighbor whenever there is work, and additionally polls every evening, the cost is DIRECT, not DIRECT+EVENING. PATHALIAS (UUCP MAP FILE FORMAT DETAILS) Page B-3 Uucp Map File Format Some examples: down princeton!(DEDICATED), tilt, %thrash(LOCAL) princeton topaz!(DEMAND+LOW) topaz @rutgers(LOCAL+1) If a link is encountered more than once, the least-cost occurrence dictates the cost and network character. Links are treated as bidirectional but asymmetric: for each link declared in the input, a DEAD reverse link is assumed. B.2.4 Terminal Links If the "to" host in a link is surrounded by angle brackets, the ________ link is considered terminal, and further links beyond this one are heavily penalized. For example, with input seismo (10), research(100), ihnp4(10) research allegra(10) ihnp4 allegra(50) the path from seismo to research is direct, but the path from seismo to allegra uses ihnp4 as a relay, not research. The way to think of this is to imagine two copies of research, one that's cheap to get to, but has no neighbors, and one that's expensive to get to, but has neighbors. (This is an exception to the "least-cost link" rule above.) B.2.5 Aliases The set of names by which a host is known to its neighbors is _______ called its aliases. Aliases are declared as follows: name = alias, alias ... The name used in the route to or through aliased hosts is the name by which the host is known to its predecessor in the route. B.2.6 Networks Fully-connected networks, such as the ARPANET or a local-area network, are declared as follows: net = {host, host, ...} The host-list may be preceded or followed by a routing character, and may be followed by a cost: princeton-ethernet = {down, up, princeton}!(LOCAL) ARPA = @{sri-unix, mit-ai, su-score}(DEDICATED) The routing character used in a route to a network member is the PATHALIAS (UUCP MAP FILE FORMAT DETAILS) Page B-4 Uucp Map File Format one encountered when "entering" the network. See also the sections on gateways and domains. B.2.7 Hidden Hosts Connection data may be given while hiding host names by declaring private {host, host, ...} Pathalias will not generate routes for private hosts, but may produce routes through them. The scope of a private declaration extends from the declaration to the end of the input file in which it appears, or to a private declaration with an empty host list, whichever comes first. The latter scope rule offers a way to retain the semantics of private declarations when reading from the standard input. B.2.8 Preventing Routing Through Certain Hosts, Links, Or Networks Dead hosts, links, or networks may be presented in the input stream by declaring dead {arg, ...} ___ where arg may be any of: o A single host name. The host is treated as dead and is used as a relay host of last resort on any path. o The form "host-1!host-2". The link from host-1 to host-2 is treated as an extremely high cost (that is, DEAD) link. o A network name. Such a declaration indicates that the network requires a gateway. B.2.9 Gateways A network is represented by a pseudo-host and a set of network members. Links from the members to the network have the weight given in the input, while the cost from the network to the members is zero. If a network is declared dead, the member-to-network links are marked dead, which effectively prohibits access to the network from its members. However, if the input also shows an explicit link from any host to the network, then that host can be used as a gateway. (In particular, the gateway need not be a network member.) For example, if CSNET is declared dead and the input contains CSNET = {...} PATHALIAS (UUCP MAP FILE FORMAT DETAILS) Page B-5 Uucp Map File Format csnet-relay CSNET then routes to CSNET hosts will use csnet-relay as a gateway. B.2.10 Domains A network whose name begins with "." is called a domain. Domains are presumed to require gateways, that is, they are DEAD. The route given by a path through a domain is similar to that for a network, but here the domain name is tacked onto the end of the next host. Subdomains are permitted. For example: harvard .EDU # harvard is gateway to .EDU domain .EDU = {.BERKELEY, .UMICH} .BERKELEY = {ernie} yields ernie ...!harvard!ernie.BERKELEY.EDU!%s Output is given for the nearest gateway to a domain. For instance, the example above gives .EDU ...!harvard!%s Output is given for a subdomain if it has a different route than its parent domain, or if all its ancestor domains are private. B.2.11 Smart Hosts Pathalias and the DECUS uucp mailer support the "smart host" notion. If a smart host is defined, and the mailer is handed an address that it can't resolve, the mail is sent to the smart host __ in hopes that it can deal with the address. To set a smart-host alias, place a line like smart-host = host | in a file called U.something in the [.DATA.MAPSRC] directory. | (Do not include this line in the map file which you mail to the | uucp mapping project! Keeping it in a separate file reduces the | chances of making this mistake.) The smart host mechanism makes it possible to completely avoid the use of the uucp maps, simply by handing all of your mail to another host for routing. NOTE It is only reasonable to contact the postmaster on "host" and obtain their permission to do this, PATHALIAS (UUCP MAP FILE FORMAT DETAILS) Page B-6 Uucp Map File Format rather than blithely assuming that they won't mind routing all of your site's mail. B.3 Output Format A list of host-route pairs is written to the output, where route is a string appropriate for use with printf(), for example: rutgers princeton!topaz!%s@rutgers The "%s" in the route string is replaced by the user name at the destination host. (This task is normally performed by the mailer.) _______ Except for domains, the name of a network is never used in routes. Thus, in the earlier example, the path from down to up would be "up!%s," not "princeton-ethernet!up!%s." B.4 Bugs And Deficiencies Terminal nets are not implemented. Pathalias can generate hybrid (that is, ambiguous) routes, which are abhorrent and most certainly should not be given as examples in the manual entry. Experienced mappers largely shun "@" when preparing input; this is historical, but also reflects uucp's facile syntax for source routes. Multiple "@"s in routes are loathsome, so pathalias resorts to the "magic %" rule when necessary. This convention is not documented anywhere, including here. APPENDIX C UTILITIES This appendix describes several utilities provided with the DECUS uucp package. All of these utilities are defined as foreign commands by [.BIN]USERCMDS.COM . Many of them (as described) include support for Unix-style I/O redirection, pipes, and execution in a spawned subprocess. UTILITIES Page C-2 | Checkaddr | C.1 Checkaddr | | This utility allows you to test the effects of your PATHS. and | MAIL_REWRITE.RULES files. | | The command checkaddr takes one or more network addresses as | arguments, optionally preceded by a rewrite rule set specifier, | as follows: | usage:^^checkaddr addr [addr ...] | or:^^checkaddr -outbound-to addr [addr ...] | or:^^checkaddr -inbound-from addr [addr...] | or:^^checkaddr -inbound-to addr [addr ...] | or:^^checkaddr -outbound-from addr [addr...] | | Addresses preceded by a rewrite rule specifier are first | translated according to the indicated rules, and then routed via | PATHS. Addresses not so preceded are simply routed via PATHS. | | The "addr" arguments must nearly always be surrounded by | quotation marks, or DCL will interpret !'s, @'s, and so on. | | Several different types of addresses may be checked in one | command, as in | | ^^^^^^^^checkaddr addr1 -inbound-from addr2 -outbound-from addr3 | UTILITIES Page C-3 Tail C.2 Tail This is a VMS version of the standard Unix "tail" utility. Its prime purpose is to read a file such as a log file and display only the last few lines (the "tail"). The following is the output of "tail -help". "-help" is an invalid option, but any invalid option causes tail to produce this usage description. usage: tail [+-][n][arf] [file] +n Begin copying at 'n' lines from the beginning of the file. If number is not specified, the value 10 is used. -n Begin copying at 'n' lines from the end of the file. If number is not specified, the value 10 is used. This option is the default if neither "-" nor "+" appears. -r Copy lines from the end of the file in reverse order. The default for 'r' is to print the entire file this way. -f If the input file is not a pipe, do not terminate after the line of the input file has been copied, but enter an endless loop, sleeping for a second and then attempting to read and copy further records from the input file. This option may be used to monitor the growth of a file that is being written by some other process. For example, the command: tail -40f barney will print the last forty lines of the file barney, followed by any lines that are appended to barney between the time tail is initiated and killed. | -a Modifies the 'f' option. The existence of both the 'a' and | 'f' switches causes tail to continue outputting even if | the file gets smaller (i.e. a new version is created). | This feature is useful with log files and others which | are periodically reopened. For example, the following | command | _ | tail -af uucplog:uucp.log & | | will always show the current (latest) version of | uucp.log, even past midnight when the UUCLEAN batch job | renames the original file. The following is a useful way to use tail with the uucp log file: $ tail -20af uucp_log:uucp.log & This writes the tail of the logfile, then continues to display additional lines as they are written. The trailing "&" causes the command to run in a subprocess, so you can continue to work at your terminal. UTILITIES Page C-4 Tail The only restriction on the "-f" option is that if the file being "tail"ed is open by another process, its growth will only be noticed when the file header is updated to reflect the new growth. This happens with batch log files once a minute or however often you specify via the SET OUTPUT_RATE DCL command. It is not a problem with the uucp log file because this file is opened anew (for append access) and closed for each write. UTILITIES Page C-5 Compress C.3 Compress C.3.1 Synopsis compress [ -c ] [ -d ] [ -f ] [ -v ] [ -p ] [ -z ] [ -b bits ] [ filename ... ] uncompress [ -c ] [ -v ] [ -p ] [ -z ] [ filename ... ] zcat [ filename ... ] Unix shell-style I/O redirection (>, <, >>, |) and background processing (&) are supported. C.3.2 Description "compress" reduces the size of the named files using adaptive Lempel-Ziv coding. Whenever possible, each file is replaced by one with one with "-Z" concatenated to the extension, while keeping the same ownership, modes and modification times. If no files are specified, the standard input is compressed to the standard output. Compressed files can be restored to their original form using "uncompress" (aka "compress -d"). This replaces the compressed file with the uncompressed version with the "-Z" removed. "zcat" produces uncompressed output on the standard output, but leaves the compressed "-Z" file intact. "zcat" (aka "compress -dc") defaults to a simple "cat" for files that are not actually compressed. C.3.3 Options -c Write to the standard output; no files are changed. The nondestructive behavior of "zcat" is identical to that of "uncompress -c", or "compress -dc". -d If given, decompression is done instead. -f Force compression of "name", even if one already exists, and even if no space is saved by compressing. Except when run in the background (or in a batch job), if -f is not given and "compress" is run in the foreground, the user is prompted as to whether an existing "name"-Z file should be overwritten. On VMS output files are not actually overwritten, a new version is merely created. -v Verbose. Display the percentage reduction for each file compressed. -b bits Set the upper limit (in bits) for common substring codes. "bits" must be between 9 and 16 (16 is the default). -p Prefixes compressed files with the string "#! cunbatchn" while compressing, and strips (and requires) this prefix from a file being uncompressed. Used for sending (compressing) and receiving (decompressing) news. UTILITIES Page C-6 Compress -z Leave name unchanged and don't impose or require "-Z" file names. filename ... Files to be compressed. If none specified, stdin is used. C.3.4 Diagnostics Exit status is normally success (1); if the last file was not compressed because it became larger, the severity is WARNING. If an error occurs, the severity is ERROR. Usage: compress [-fvc] [-b maxbits] [file ...] Invalid options were specified on the command line. Missing maxbits Maxbits must follow -b. "file": not in compressed format The file specified to "uncompress" has not been compressed. "file": compressed with "xx" bits, can only handle "yy" bits "file" was compressed by a program that could deal with more "bits" than the compress code on this machine. Recompress the file with smaller "bits". "file": already has -Z suffix -- no change The file is assumed to be already compressed. Rename the file and try again. "file" already exists; do you wish to overwrite (y or n)? Respond "y" if you want the output file to be replaced; "n" if not. uncompress: corrupt input A SIGSEGV violation was detected, which usually means that the input file is corrupted. Compression: xx.xx% Percentage of the input saved by compression. (Relevant only for -v.) -- not a regular file: unchanged When the input file is not a regular file, (e.g. a directory), it is left unaltered. -- file unchanged No savings are achieved by compression. The input remains uncompressed. UTILITIES Page C-7 Compress C.3.5 Notes This program uses the same algorithms as LZCMP and LZDCM, which are widely distributed through DECUS; in fact, we have used LZDCM to unpack "compress"ed files. The only reason we need "compress" is to support the "#!cunbatch" header line placed in compressed News batches. It seemed better to supply what looks like a completely different program for this purpose than to modify LZCMP and LZDCM, since those programs are being maintained by other people. "compress" should only be used on files that won't be bothered by conversion to stream-LF format, as it does not preserve record attributes (or other information from the file header). The amount of compression obtained depends on the size of the input, the number of "bits" per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60%. Compression is generally much better than that achieved by Huffman coding (as used in "pack"), or adaptive Huffman coding ("compact"), and takes less time to compute. The "bits" parameter specified during compression is encoded within the compressed file, along with a "magic number" to ensure that neither decompression of random data nor recompression of compressed data is subsequently allowed. C.3.6 References "A Technique for High Performance Data Compression", Terry A. Welch, "IEEE Computer", vol. 17, no. 6 (June 1984), pp. 8-19. UTILITIES Page C-8 Uurate - Report Transfer And Connect Times For Uucp Calls C.4 Uurate - Report Transfer And Connect Times For Uucp Calls C.4.1 Synopsis uurate [-s] [-c] [-h hostname] logfile ... logfile C.4.2 Description "uurate" scans the specified uucp log files extracting and accumulating transfer rates and connect times for inbound and outbound uucp processing. Logfile names may include standard VMS wildcards. C.4.3 Options -s Separate dialed in vs. dialed out statistics in the resulting report. The default is to report combined statistics. -c Include information about uuxqt activity (rmail, rnews) -h host Restrict report to logfile entries relating to the indicated uucp neighbor C.4.4 Example Output C.4.4.1 Example 1 $ uurate -c uucp_log:uucp.log_0424 We called simpact 9 times, 66 secs, they called in 4 times, 1163 secs We called esther 0 times, 0 secs, they called in 6 times, 36 secs We called lupine 7 times, 2830 secs, they called in 1 times, 1441 secs We called athertn 20 times, 212 secs, they called in 1 times, 332 secs got from simpact 6 files 252896 bytes 1105 secs 228.87 bytes/sec got from lupine 2 files 317221 bytes 1431 secs 221.68 bytes/sec got from athertn 12 files 26157 bytes 52 secs 503.02 bytes/sec sent to simpact 4 files 2896 bytes 10 secs 289.60 bytes/sec sent to lupine 12 files 1060339 bytes 2679 secs 395.80 bytes/sec sent to athertn 10 files 292268 bytes 293 secs 997.50 bytes/sec simpact live 1229 secs dead 114 secs esther live 36 secs dead 36 secs lupine live 4271 secs dead 161 secs athertn live 544 secs dead 199 secs Work from simpact initiated the following commands: 3 executions of rmail Work from lupine initiated the following commands: 1 executions of rnews Work from athertn initiated the following commands: UTILITIES Page C-9 Uurate - Report Transfer And Connect Times For Uucp Calls 3 executions of rnews 3 executions of rmail C.4.4.2 Example 2 $ uurate -sc UUCP_LOG:uucp.log_0424 simpact called us 4 times, 1163 secs got from simpact 6 files 252896 bytes 1105 secs 228.87 bytes/sec sent to simpact 2 files 1889 bytes 5 secs 377.80 bytes/sec we called simpact 9 times, 66 secs sent to simpact 2 files 1007 bytes 5 secs 201.40 bytes/sec esther called us 6 times, 36 secs lupine called us 1 times, 1441 secs got from lupine 2 files 317221 bytes 1431 secs 221.68 bytes/sec we called lupine 7 times, 2830 secs sent to lupine 12 files 1060339 bytes 2679 secs 395.80 bytes/sec athertn called us 1 times, 332 secs got from athertn 4 files 4283 bytes 15 secs 285.53 bytes/sec sent to athertn 6 files 283071 bytes 278 secs 1018.24 bytes/sec we called athertn 20 times, 212 secs got from athertn 8 files 21874 bytes 37 secs 591.19 bytes/sec sent to athertn 4 files 9197 bytes 15 secs 613.13 bytes/sec simpact live 1229 secs dead 114 secs esther live 36 secs dead 36 secs lupine live 4271 secs dead 161 secs athertn live 544 secs dead 199 secs Work from simpact initiated the following commands: 3 executions of rmail Work from lupine initiated the following commands: 1 executions of rnews Work from athertn initiated the following commands: 3 executions of rnews 3 executions of rmail (The "live" times show total times for all calls; "dead" refers to those periods within the calls when no data is being transferred: Login, protocol negotiation, searching for work, etc.) C.4.5 Notes Uurate is run automatically once a day by the UUCP_CLEANUP batch job. The resulting report is mailed to UUCP_POSTMASTER. UTILITIES Page C-10 Uurate - Report Transfer And Connect Times For Uucp Calls C.4.6 Bugs As might be expected of a utility ported from Unix, the "-s" option here has a completely different meaning than the "-s" option to uucico. We'll fix this in a later release. APPENDIX D ADDRESS FORMATS This appendix provides a brief introduction to the construction and use of network addresses. D.1 The Simple Cases D.1.1 How Do People Send Mail To Me? Until you are registered as an Internet domain, you can tell people that your network address is yourhost!user (where "yourhost" is your uucp host name, and "user" is your regular VMS username). A lot of mail sent that way won't get to you until your map entry gets out to the world in general, so for a month or two at least, it's best to publicize an address like well-known-host!intermediate-host!...!...!yourhost!user where the ellipses represent whatever other sites are in the path between you and the well-known-host. In fact, it's best to continue this practice indefinitely, since many uucp sites still aren't using the maps. If your host is connected to several well-known hosts, you might publish something like this: {wkh1, wkh2, wkh3}!yourhost!user The commas are interpreted as meaning "or". Received mail sent to yourhost!user will be placed in that user's VMSmail NEWMAIL folder, just like regular VMSmail. The VMSmail "From:" line will show UUCP%"...", where ... will usually be in a form acceptable to the uucp mail router. In other words, the VMSmail REPLY command should work. (If it doesn't, see the next sections.) Do not advertise yourself as having a "domainized" name (for example, user@yourhost.companyname.com) until your domain is officially registered. ADDRESS FORMATS Page D-2 The Simple Cases As discussed in the chapter on Internet domain registration, many sites use ".uucp" as a domain, e.g. user@yourhost.uucp until they are officially registered. This used to be benign, but ".uucp" is now an officially recognized Internet zone (but not a domain). The ".uucp" practice is still widespread, however, and in fact many Internet sites have mailers that can (usually) send to "user@host.uucp" automatically, so unregistered uucp sites will probably continue to publicize names of this form. Note that the mail router used here and at many other uucp sites makes it possible to send to "user@host" as long as the host is ___ known in the uucp maps. But the success of this syntax does not mean that the site in question has an officially registered "domain name". See the chapter on Internet Domain Registry for more details. D.1.2 How Do I Send Mail Out? ____ For most sites, you will be able to respond to the VMSmail "To:" prompt with UUCP%"user@site" ____ where site is usually something like machine.organization.domain ____ , but may be as simple as a uucp host name, and user is a username on that system. If someone gives you an address like remhost!user you can generally use a VMSmail "To:" address of UUCP%"user@remhost" If you get something in the more complex form shown previously, well-known-host!intermediate-host!...!...!theirhost!user you can try sending to UUCP%"user@theirhost" first; if that doesn't work, just wrap UUCP%"..." around the whole mess. You needn't worry about how to get to well-known-host: If it's well-known it'll be in the maps, and the mailer will figure out the path from your system. If your addressee has given you an address like {wkh1, wkh2, wkh3}!theirhost!user ______ you cannot pass this to Mail directly. The idea is that you are ___ supposed to figure out how to get to one of the "well-known-hosts" mentioned (your choice as to which). So try something like UUCP%"wkh2!theirhost!user" ADDRESS FORMATS Page D-3 The Complex Cases D.2 The Complex Cases The above techniques will often fail for @-form addresses when networks other than uucp or Internet are involved (and sometimes even then). This is particularly true of Bitnet, which uses Internet-style addresses and otherwise looks like part of the Internet, but isn't really. The general solution is to "send the mail through a gateway". A later version of this document will expound upon the possibilities. For now, refer to the files in [.DOC.ADDRESSING], which are mostly a collection of questions and answers on these issues that have appeared on the net. D.2.1 Percent Signs Many addresses include imbedded percent signs; for example: TNIELAND%FALCON@AAMRL.AF.MIL There are differences of opinion as to how this should be interpreted. In general it usually is interpreted with everything to the left of the "@" as being a "funny username", so the mail is sent to TNEILAND%FALCON at AAMRL.AF.MIL on the assumption that aamrl.af.mil will know what to do with it. (In this particular case, they do.) Troubles may arise when addresses of this form are handed to uucp (any uucp, not just ours). For uucp transmission we must convert __________ everything to bang-path notation, so we end up with something like neighbor!...!AAMRL.AF.MIL!TNEILAND%FALCON This works fine when I send mail to this address (actually I send to UUCP%"TNIELAND%FALCON@AAMRL.AF.MIL"), but Tom Allebrandi's uucp "neighbor" hates to see !'s and %'s in the same address, and either bounces it as undeliverable or does horrible things to it. Tom gets around this by converting the % to a ! himself, sending to UUCP%"FALCON!TNEILAND@AAMRL.AF.MIL" This workaround succeeds in this particular case because aamrl knows to handle falcon!tneiland just as it would handle tneiland%falcon. In the general case, success depends on the capabilities of the target Internet host. The next section discusses addresses of this form in more detail. ADDRESS FORMATS Page D-4 The Complex Cases D.2.2 Mixed Uucp/Domain Addresses Sometimes you will see an address of the form uuhost!user@inethost.company.com Such an address, combining "!" and "@" notation (with maybe some "%"s thrown in for good measure), is referred to as a "mixed mode" address. These addresses are often used by uucp sites (uuhost in this example) who do not have registered domain names, but have a uucp connection to a nearby host (inethost.company.com) who does. In general more sites will know how to get to inethost.company.com than to uuhost, so they are trying to make it easy for people to send mail to them. If someone -- particularly someone on the Internet -- is having trouble sending mail to you, you might try telling them to use such an address. For example, if you know of an Internet site (isite.dom.ain) that reaches you reliably via uucp, you might suggest that they try yourhostname!you@isite.dom.ain meaning "send mail to isite.dom.ain, who will send it to yourhostname!you". Addresses of this form should not, in general, be published "at large" as your "standard" address, but only given out to individual correspondents to solve particular problems. DECUS uucp will generally do the right thing when asked to send mail to an address like this, but this is not true of all other uucp systems. This is because the interpretation of such an address as a mail destination varies depending on the machine sending the mail. Using the second example above: If the machine from which mail is being sent to you understands "@"-signs (as DECUS uucp machines do), this address is equivalent to isite.dom.ain!yourhostname!you meaning "send it to isite.dom.ain, who will send it to yourhostname!you, which is what you want. (In practice there will probably be some additional hosts in the bang-path prior to isite.dom.ain .) But a "pure uucp" machine might send it this way: yourhostname!isite.dom.ain!you which is obviously wrong, since the pure uucp machine likely doesn't talk to yourhostname. (If they do, they can just send to yourhostname!you and avoid all this bother.) Even if the message does get to yourhostname, this address tells yourhostname to send it to isite.dom.ain, and you don't live there! ADDRESS FORMATS Page D-5 The Complex Cases So, in general, it is a bad idea to publicize addresses of this form. If you want an "@" in your e-mail address, register your site as an Internet domain, as described in a subsequent chapter. APPENDIX E HOW IT WORKS E.1 The Basics When you send mail to UUCP%"user@somewhere", VMS MAIL activates the UUCP_MAILSHR image, which in turn uses the path data base to find an appropriate route. The route will be of the form ______ system!system2!...!user. The first system in the route will be name of the neighbor system to which your mail will be sent for forwarding. In the filename examples to be given, this will be called system "them", and your system will be called system "us". UUCP_MAILSHR then creates three files in UUCP_SPOOL: o B.usAnnnn - a uuxqt command file to be sent to the remote system o C.them_Annnn - commands to the local uucico program o D.usAnnnn - the actual mail file, with RFC822 headers When uucico looks for work for "them" (either when deciding whether to call them, or when they call us), it will find the C file. (C files are in fact sometimes referred to as "work files".) This file tells it to copy the D file to the remote system as-is, and to copy the B file with its name changed to X.usAnnnn . NOTE In order to prevent uucico from finding C files before UUCP_MAILSHR is done with them, the C file is not directly created. Instead, UUCP_MAILSHR creates the file as Z.them_Annnn. The last thing UUCP_MAILSHR does for outgoing mail is to rename Z.them_Annnn to C.them_Annnn, thus making the file available to uucico. You should never see Z ____ files in the spool directory (other than very briefly) -- if you do, something is wrong. To process incoming mail, uucico awakens uuxqt whenever uucico receives an X file. uuxqt looks for X files in the spool directory. The X file tells uuxqt which files in the spool HOW IT WORKS Page E-2 The Basics directory to access and what command to execute on the receiving system to process those files. For mail, this command is ____ "rmail". (We have hardwired our uuxqt so that it only responds to rmail and rnews commands.) Rmail in turn delivers the mail to the intended recipient, (perhaps by sending it, via uucp, to the next system in the path). E.2 Details: B, X, C, And D Files We are going to cop out here and refer you to the relevant ________ ____ ___ sections of Appendix A, "Working Files", in Managing uucp and ______ Usenet (see Chapter 0). We hope to find time to expound upon the "internals" in a future version of the manual. E.3 Locks DECUS uucp uses the VMS lock manager to trigger uuxqt wakeup (via a "doorbell" lock, using a blocking AST), and also to prevent multiple uucico processes from trying to contact the same neighbor at the same time. For example, when an incoming call is received, uucico attempts to acquire (in exclusive access mode) a lock with the name UUCP_SYS_hostname Similarly, the uucico daemon attempts to acquire the same lock when processing the systems file entry for hostname. Only one of these processes can own the lock at one time, so multiple contacts are prohibited. Access to the serial ports is controlled through VMS's standard implicit device allocation mechanism; since the terminal ports are nonshareable devices, no two processes can simultaneously have a channel assigned to one port. No Unix-style "lock files" are used. If a uucp process is "stuck", and holds a lock which prevents its replacement from functioning, simply delete the "stuck" process with a DCL STOP/ID command. This will release all locks owned by the process. The SHOW LOCKS and SHOW PROCESS/LOCKS commands to the system dump analyzer (invoked with ANALYZE/SYSTEM) will display all of the locks known on your system, and all of the locks held by a given process, respectively. These commands may be of use in finding out which processes are holding the locks in question. E.4 Unix Compatibility Issues HOW IT WORKS Page E-3 Unix Compatibility Issues E.4.1 Stream Files VMS files opened for reading (that is, for transmission to a remote uucp system) are always opened for stream access. Thus, even if the file was not written in stream mode, uucico sees it as if it was. File opened for writing (that is, files being received from a remote system) are opened for writing in stream mode. E.4.2 Lower Case In File Names Some Unix uucp implementations send D- and X-files with sequence "numbers" that can include not only the ten digits but also the fifty-two upper- and lower-case characters. Unix distinguishes case in filenames: "A.TXT" is not the same file as "a.TXT". We've seen instances where a Unix system sent us two sets of files, with sequence "numbers" that differed only in case. We correct this by applying the following transformation to file names received from any remote uucp system: We scan the file name extension from left to right, and insert an underscore (_) _______ every time the case changes. The extension is assumed to start in lower case (as it does, since the first thing in the extension is the remote system name, which is always in lower case.) This is done by uucico, when we receive both the X- and D-files. It is also done within uuxqt, when we encounter the D-file name in "F" and "I" commands in the X-file. E.5 Uucp Protocol Details For additional details on the uucp "g" protocol, see the document [.DOC]UUGPROT.MEM . APPENDIX F TROUBLESHOOTING DECUS uucp has an extensive system of log files to help keep you informed of what it is doing. Most failures can be quickly analyzed by examining the log files and the appropriate records in the regular VMS accounting file. This appendix will describe the various log files and conclude with a discussion of common and likely problems. F.1 UUCP.LOG This single file is uucp's primary event log. It appears in the log directory [.LOG] (as do all of the other log files described in this appendix). All processes running uucico (both the dialout daemon and for incoming calls), as well as uuxqt, append entries to this file to record "major events". Most problems will be recorded in this file. The causes for the problems will generally not be obvious, but as will be seen, entries here will usually point you to other log files which will provide more information. Somewhat like VMS's error log, uucp.log is opened for append access and then closed again every time an entry is added. This causes a bit of extra overhead but means that the latest entries in the file are always immediately accessible for viewing. The uuclean batch job (UUCP_CLEANUP) renames this file to UUCP.LOG_mmdd each night, shortly after midnight, so that no one file gets too large. Uuclean also searches the previous day's UUCP.LOG file(s) for entries denoting errors and mails such entries to the UUCP_POSTMASTER. Here is a sample entry from uucp.log: p:uucp << h:esther [04/20-16:48:49-0000051a] Startup ok (g) u:- We will eventually write many tens of pages about all of the different log entries that can appear and what they all mean. (The adventurous and the impatient can look for calls to the procedure logit() in [.DEVEL.UUCP.SRC]*.C .) For now, we'll describe the entry format and point out a few perhaps-non-obvious details. TROUBLESHOOTING Page F-2 UUCP.LOG F.1.1 UUCP.LOG Entry Format Log entries follow a consistent format. Reading from left to right, the elements of an entry are: F.1.1.1 Program Name The name of the program that made the entry, preceded by "p:". This will be either "uucp" (which really means uucico) or "uxqt" (short for uuxqt). Uuxqt's entries are rarely interesting. F.1.1.2 Call Progress And Direction Indicator Two "funny characters" that together indicate the direction and status of a call. For entries from "uucp", the combinations that can appear are: (empty) program startup -- sleeping, waiting for work ?> scanning spool directory for work -> placing call to system named in "h:" => dialed ok, doing login script and protocol handshake >> handshake succeeded, exchanging work -< incoming call received =< incoming call, doing protocol handshake << handshake succeeded, exchanging work This may seem excessively cute, but it lets us pack a great deal of information into each log entry in a minimum amount of space. There is no need to find the most recent "Incoming" and "Outgoing" messages to determine the system name and call direction for any given log entry, since this information appears _____ in every log entry. Note that for "uucp" entries the arrow does not indicate the direction of data transfer, but the direction of the telephone call. (A left-pointing arrow is an incoming call -- to uucp -- while a right-pointing arrow is an outgoing call, usually from the uucico daemon.) Data can always be exchanged in both directions during any given call. For "uxqt" entries (other than program startup) there is a much smaller set: =< beginning X file processing << handing X file contents to UUXQT\_DCL F.1.1.3 Hostname The uucp hostname of the system at the other end of the serial link, preceded by "h:". TROUBLESHOOTING Page F-3 UUCP.LOG F.1.1.4 Date, Time, And PID Stamp The date (month and day only) and time the log entry was made, and the VMS process identification (PID) of the process that made the entry, all surrounded by square brackets. As will be seen, the PID is the key to several other vital pieces of information. F.1.1.5 Error Indicator This is an asterisk in the second character position after the closing bracket of the time-and-pid field. It does not appear in the preceding example, because that entry did not denote an error. Here is a sequence that includes some error indicators: p:uucp -- h:- [04/20-17:50:38-00000487] Waiting (15 minutes) u:- p:uucp ?> h:crash [04/20-17:53:28-00000487] Outgoing (_TTB1: 2400 bps) u:- p:uucp -> h:crash [04/20-17:53:28-00000487] Calling (crash) u:- p:uucp -> h:crash [04/20-17:54:02-00000487] * Script log (Modem reported NO CARRIER) u:- p:uucp -> h:crash [04/20-17:54:03-00000487] * Dial failed (crash) u:- p:uucp -> h:crash [04/20-17:54:03-00000487] Dropping DTR () u:- p:uucp -> h:crash [04/20-17:54:10-00000487] * Call failed (see prev msg) u:- p:uucp -- h:- [04/20-17:54:11-00000487] Waiting (15 minutes) u:- ("crash" is the uucp host name of the system being called, not a description of what happened afterwards.) The asterisk is there to call your attention to the errors amongst all of the other entries. Sometimes (as seen here) other nearby entries will provide more information. The "Script log" entry was generated ___ by a log statement in the dial script, and the "Modem reported NO ___ CARRIER" text was the argument of the log statement. The script ______ then exited by executing a failed statement, causing uucico to write the "Dial failed" log entry. F.1.1.6 Event Description A very brief statement of the event, followed (usually) by additional information pertaining to the event. The latter is enclosed in parentheses. F.1.1.7 Username Preceded by "u:". Immediately after startup of uucico, contains the VMS username associated with the process. After a connection is established with a remote uucp host, and work is being exchanged, this field reflects the name of the user who requested the action that is being reported by the log entry. Often appears in hostname!user or user@host.domain format, and may reflect a username on the local system or the neighbor system, depending on the entry. If unknown or not applicable at this point in the call, appears as "-". TROUBLESHOOTING Page F-4 UUCP.LOG F.1.2 Hints On Log File Interpretation F.1.2.1 Time Sequencing We should mention once again that all processes running uucico or uuxqt append entries to this file. The following sequence, for example, shows mail being received by uucico, and processing of the "rmail" command by uuxqt before uucico exits: p:uucp << h:esther [04/20-16:48:55-0000051a] They want to send (S D.estherA0794 D.estherA0794 jeh@SIMPACT.UUCP - D.estherA0794 0666 ) u:jeh@SIMPACT.UUCP p:uucp << h:esther [04/20-16:48:59-0000051a] File rcvd ok (370 bytes, 3 secs, 123 Bps) u:jeh@SIMPACT.UUCP p:uucp << h:esther [04/20-16:49:01-0000051a] They want to send (S B.estherA0794 X.estherA0794 jeh@SIMPACT.UUCP - B.estherA0794 0666 ) u:jeh@SIMPACT.UUCP p:uucp << h:esther [04/20-16:49:04-0000051a] File rcvd ok (70 bytes, 2 secs, 35 Bps) u:jeh@SIMPACT.UUCP p:uxqt =< h:esther [04/20-16:49:04-00000481] Processing (X.esther_A0794) u:- p:uxqt << h:esther [04/20-16:49:04-00000481] Executing (rmail jeh < uucp_spool:D.esther_A0794 > NL:) u:- p:uucp << h:esther [04/20-16:49:08-0000051a] End of call (complete) u:jeh@SIMPACT.UUCP p:uucp << h:esther [04/20-16:49:08-0000051a] Dropping DTR () u:jeh@SIMPACT.UUCP It can get worse: If you have more than one modem, your uucico daemon might be calling out on one line while someone is calling in on another; you'll see the entries from two "uucp"s interspersed in the log. The PIDs will let you sort things out; that's why they're there. F.1.2.2 Throughput As shown in the following example, uucico will report the net | throughput in bytes per second after each file transfer: ...0000051a] File rcvd ok (370 bytes, 3 secs, 123 Bps) u:jeh@simpact.uucp Do not expect throughputs approaching the line speed unless the file is large enough to need ten to twenty seconds to transfer. The actual transfer time for short files like the one reported in the preceding example is overshadowed by the startup and shutdown times for the file copy operation, and these are not compensated for in the throughput calculation. F.1.2.3 Benign "Errors" There is one "error message" that may appear after a call on a noisy line: ...00000487] * Protocol stats (errs: 1 pks in/out: 5/13) u:jeh Do not be alarmed by the non-zero "errs:", as this (probably) does not indicate that bad data was received. The uucp "g" protocol does a sixteen-bit checksum validation on each 64-byte data segment, and each six-byte packet header (which includes the checksum) is further protected by an XOR byte. We say "probably" because the simple checksum algorithm used will let some single-bit errors slip by, but is quite good at detecting the TROUBLESHOOTING Page F-5 UUCP.LOG "bursty" errors that predominate in serial communications. F.1.2.4 Sys$Assign: No Privilege For Attempted Operation Uucico may report this error when it tries to assign a channel to a port to place an outgoing call. It may mean that the device protection mask or ACL has not been set properly (see the SET DEVICE/ACL commands in UUCP_SYSTARTUP.COM); this should be fixed. But it may also simply mean that some other process was using the port at the time. F.1.2.5 Entry Names Vs. System Names The hostname (h: field) in log entries for outgoing calls is taken from the field in the systems entry being used. If you have several systems entries for a single neighbor system, this could be a bit ambiguous, particularly when looking at "dial failed" (which number was it dialing?) and the like. So, for the following event descriptions, the from the systems entry appears in the supplemental information (within parentheses): o Calling o Dial failed o Login failed o Sys entry too short o No ports avail o Bad The supplemental information field is used for other things in other log entries, so only the (perhaps ambiguous) hostname field will appear (after the h:). However, you can find the related systems file "entry name" by looking for one of the above messages (at least one of them will always appear for any outgoing call) with a matching PID field. See the description of the and fields in systems file entries in the chapter, "Configuring UUCP", for more information. F.1.2.6 Using "SEARCH" The VMS SEARCH command can be used to good advantage to find "interesting" entries in the log. This is the reason for some of the punctuation in the log entries; it allows us to easily specify unambiguous search targets. For example, $ search esther might find places in the log where "esther" appeared in file TROUBLESHOOTING Page F-6 UUCP.LOG names, but $ search "h:esther" will just match where esther appears as a host name. $ search "0000051a]" will match all entries from the given process ID , and $ search "] * " will find all errors. Multiple search targets can of course be combined via the /match qualifier. For example, $ search "h:crash","] * "/match=and will find all error entries associated with host crash, and $ search "> h:crash","] *"/match=and will limit the search to outbound calls only. F.2 The Debug Log File In addition to the UUCP.LOG "event log", uucico is thoroughly laced with code which provides for writing to its "debug log". (Uuxqt also writes to a debug log, but its debug output is far less interesting.) Debug output is divided into a number of categories, each controlled by a bit in the debug enable mask. (These bits are documented in the example systems file, [.CFG]SYSTEMS.EXAMPLE.) The control file sets the default value for this mask, but as we have seen, each entry in the systems file can provide an overriding value which is in effect for any call using that entry. Many of the debug log options are useful only to people debugging uucico, but others are useful for troubleshooting configuration problems, and login and dial script problems in particular. The most interesting debug options for typical uucp sites will be: 000001 error messages and a copy of the log file output 000002 dial,login,init trace -- errors only 000004 dial,login,init trace -- nonerrors (incl char I/O) 000010 file transfer commands -- errors only 000200 packets -- errors only (all specified in octal). "Or" these together and you get 217, the value supplied in the example files. The single most useful thing here will likely be the dial, login, and init trace (option 4), which includes a complete record of all characters sent and received during the processing of the dial and login scripts, together with script state transitions and so on. TROUBLESHOOTING Page F-7 The Debug Log File If, for example, you aren't using the correct password to login to a particular neighbor, the debug log (with this option enabled) will show the "User authorization failure" message (or equivalent) sent by the remote system. Nonprintable characters in the log are shown in hex, using the | notation 0xhh. Printable characters with the high bit set are | shown with a leading `. Every time one second (approximately) passes while processing the waitfor statements in a state, the word "tick" is written to the log. (It is after each of these ______ _______ ticks that ifcarr and timeout statements, if present in the state, are checked. The ticks are not necessarily a full second _______ apart, but this does not affect the accuracy of the timeout.) NOTE One of the debug mask values, 004000, enables a probabilistic error generator within the "g" protocol module. This simulates line noise; we used it to ensure that our "g" protocol implementation would recover properly under various sequences of error conditions. Special entries in the control file must also be present for this feature to work. See the giowvms.c and uumisc.c modules for details. F.2.1 Where Does The Debug Log Go? Unlike UUCP.LOG, debug logs are not shared; each process running uucico (or uuxqt) has its own, so all entries therein pertain to just that one process. F.2.1.1 Inbound Calls By default uucico writes its debug log output to the "standard output" (SYS$OUTPUT in VMS parlance). This is obviously unsuitable for inbound calls, where SYS$OUTPUT points to the serial port, so the debug log is redirected at a file called [.LOG]UUCICO_DBG.pid, where pid is the process id, in hex (but not zero-filled, so on a non-clustered machine the filename extensions are nice and short). Use the entries in uucp.log to find the pids that are of interest. For example, when looking at the following log excerpt p:uucp -< h:- [04/20-17:35:18-00000527] Incoming (_TTB1: 2400 bps) u:- p:uucp -< h:crash [04/20-17:35:19-00000527] Call from (crash) u:- p:uucp =< h:crash [04/20-17:35:24-00000527] Carrier lost () u:- we could expect to find some clues as to what happened in [.LOG]UUCICO_DBG.527 (and also in the system accounting file). ("Carrier lost" doesn't have an error indicator because this event occurs during the normal sequence of every call; it just happened early this time.) TROUBLESHOOTING Page F-8 The Debug Log File Once a night, the uuclean batch job deletes files with names of this form which are over a day old and for which there are no error entries in UUCP.LOG. F.2.1.2 Outbound Calls For outbound calls, the uucico daemon writes the debug log to its SYS$OUTPUT, which is its batch job log file, [.LOG]UUCICO_CALLOUT.LOG . | | In earlier versions, some of the debug output that was written to | the batch job log file would appear one character per line, as | follows: | | Sending slowly: | A | T | Q | 0 | 0x0D | Doing expects for state wakemodem | Received: | A | T | Q | 0 | . | . | . This has been corrected. F.3 SYS$ERROR For inbound calls, SYS$ERROR is directed to a file called [.LOG]SYSERROR.pid where "pid" is, again, the process identification (without leading zeroes). These files can help find login and startup problems caused by protection violations and similar difficulties. Zero-length files with names of this form are automatically deleted once an hour by the UUCP_CLEANUP batch job. For outbound calls, SYS$ERROR is of course the batch job's log file, [.LOG]UUCICO_CALLOUT.LOG . If uucico should ever terminate abnormally (perhaps with an access violation), you'll find the traceback output in one of these files. (Please mail it to one of the authors as soon as possible!) TROUBLESHOOTING Page F-9 Status Files F.4 Status Files These are not, strictly speaking, log files; they are used by uucico to record the completion status of the most recent call to or from each neighbor system. Their names are [.LOG]STST.hostname . Each contains just one line of text. For example: f: 0 c: 6 nf: 0 sq: 348 success outbound normal - [04/21-00:11:45-00000487] The latter part of that should look familiar: It's the same as the time-and-pid stamp in the log file. At the beginning of the line are four numeric fields, set off by short, minimally- mnemonic codes: f: 0 or 1 to indicate success or failure, respectively c: a numeric code representing the completion status nf: the number of successive failures sq: call sequence number Following this is a textual interpretation of the "c:" value. These files are used by the call time decision mechanism in the uucico daemon. Note that the revision date and time of the file, and not the date and time stored in text in the file, is used to determine "time of last call": If you edit one of these files, uucico will assume that the last contact was at the time you edited the file. (One good reason for editing an STST file is to set a large nf count to zero after a long-standing problem has been fixed, to circumvent the failure retry backoff mechanism.) F.5 UUXQT's Batch Log Uuxqt, the program that handles incoming "execution" files, runs in a batch job by itself and so has its own batch log, [.LOG]UUXQT.LOG. The SYS$OUTPUT from uuxqt's DCL subprocess gets written here too. There normally won't be much in this file except messages from UUXQT_DCL indicating the start of processing of each X-file. Any DCL error messages found in this log should be reviewed carefully; they will probably be associated with files in [.DUMP] (to be described) and/or [.RCVDNEWS], and possibly [.SPOOL]. F.6 Other Sources Of Information F.6.1 The Dump In the [.DUMP] directory you may find X- and D-files. These are received X- and D-files which could not be processed correctly. Entries in uucp.log, and possibly uuxqt_dcl.log, should indicate the reason. You can search for the file name in uucp.log, or look at the creation dates and search the log file for the appropriate "mm/dd-hh:ss" strings. Also, find the appropriate UUXQT.LOG file (using creation dates) and look in it for the file TROUBLESHOOTING Page F-10 Other Sources Of Information name. F.6.2 Temporary Files In The Spool Directory The existence of one or more files called TM_Unnnn in the spool directory when uucp is not handling and incoming or outgoing call indicates that a previous call failed in the midst of a file transfer. Uucico always receives data into files named in this way; when the entire file has been received correctly, uucico renames it to the proper name (D.* or X.* for mail and news). Check the creation date on each such file, and search UUCP.LOG for entries around that date and time; these will tell you the name of the sending system and the intended final filename. The sending system should send you the file again during a later call, as uucp never deletes outgoing files until they have been transferred successfully. You can therefore safely delete these TM_Unnnn files; we leave them in the spool directory so that their presence will alert you to possible problems. Note that, dialup phone lines being what they are, occasional unexpected disconnects are only to be expected. Only when disconnects occur repeatedly, perhaps during contacts with a particular neighbor, are they cause for concern. F.6.3 The VMS Accounting File Don't forget that you can ask the Accounting utility to show you entries by PID: $ accounting/ident=xxxxxxxx/full The "Final status text" displayed here may point out some problems such as file protection conflicts, password troubles for inbound calls, and so forth. F.6.4 Process Names Any process running uucico or uuxqt will set its name to just like the first three log entry fields of its most recent log entry, but without the "u:" and "h:" delimiters. So SHOW SYSTEM will tell you what uucp processes exist, what they're doing, and who they're talking to (if anybody). For example, the following excerpt lines from a SHOW SYSTEM display show the uucico daemon (PID 116) in the midst of an outgoing call to scubed, and another process (PID 560) servicing in incoming call from crash. The uuxqt batch job and its DCL subprocess (PIDs 356 and 357) are, for the moment, idle. 00000116 uucp >> scubed HIB 9 103982 0 00:26:28.84 85508 693 B TROUBLESHOOTING Page F-11 Other Sources Of Information 00000356 uxqt -- - HIB 6 1586 0 00:00:26.38 7502 86 B 00000357 uxqt dcl LEF 7 4973 0 00:03:00.32 37929 203 S 00000560 uucp << crash HIB 8 1384 0 00:00:12.16 980 762 F.6.5 UUCP_STATUS Logical Name Whenever a process running uucico writes a "major" entry into the log, it copies the entry into the equivalence-name of the system logical name UUCP_STATUS_uucp. SHOW SYSTEM will thus give you a quick glance at everything that's happening with uucp, and SHOW LOG UUCP_STATUS* will show you the last log entry, without having to look at the file. F.6.6 UUSTAT.COM This command procedure (in [.BIN]) will display all lines from "SHOW SYSTEM" that reflect process names beginning with "uucp" or "uxqt", display the contents of all [.LOG]STST.* files, list all %.* files in [.SPOOL], and display the value of the UUCP_STATUS_uucp logical name. F.6.7 Tail ____ The tail utility (in [.BIN]) can be used to conveniently examine the last few lines (which are often the most interesting) in any of the log files. Tail is described in one of the appendices. F.7 "Expected Problems" As noted earlier, the places where you can expect to see problems have to do with dial and login script processing and with file protection. File protection problems will show up as VMS error messages in the uucico daemon's batch job log file, UUCICO_CALLOUT.LOG (for outgoing calls), and in the SYSERROR.pid files (for incoming). Dial and script processing applies only to outgoing calls; the after-the-failure info can be found in UUCICO_CALLOUT.LOG . Sometimes it helps to place the outgoing call from your terminal -- seeing the log output "as it happens" often makes the problems much more obvious than when you're reading the log files. If you are having real problems with your dial or login scripts, the best way to find them is to "play computer". Use Kermit, SET HOST/DTE, VAXNET, or other "terminal emulator" to connect your terminal to the modem, and try to "execute" the dial and login scripts just as uucico would. After you successfully log in to the remote system using the uucp login, you should shortly see the message Shere TROUBLESHOOTING Page F-12 "Expected Problems" or, possibly, Shere=theirhostname and the cursor should stop at the end of the message. This message is sent by the uucico in the other machine when invoked in "slave mode" (that is, when handling an incoming call). (There's not much else you can do from your terminal, so hang up the phone at this point.) If you seem to log in successfully but _____ don't see the Shere (perhaps a command line interpreter prompt appears instead), your uucp login is not set up correctly on the neighbor system. Of course, when someone calls your system, and UUCP_LOGIN invokes uucico, it sends "Shere" back to the caller. If others are having problems calling you, try logging into one of the "real" uucp logins (not the test account) yourself. If something other than "Shere" appears after you've supplied the correct username and password, something is wrong with the account setup; perhaps its default device, directory, or login command procedure are wrong. F.8 Restarting The Batch Jobs If any of uucp's batch jobs fails for any reason, enter the following DCL command to restart them: $ @UUCP_BIN:UUCP_SYSTARTUP BATCH_JOBS The parameter causes the command procedure to only start the batch jobs and not redefine the logical names, etc. Only those batch jobs which have actually failed will be restarted. | | | F.9 "MicroVAX Crashes While Running DECUS Uucp" | | This was the synopsis of one of the first bug reports we got | after Version 1.1 was released. Now, DECUS uucp is all user-mode | code, so it isn't supposed to be able to cause a crash. But it | certainly can exercise some parts of system code in ways that | expose previously-latent bugs. | | The culprit in every one of these cases was a third-party | controller in the Q-bus (typically a disk controller) that | interrupted at BR5 rather than BR4 (which is what the VMS disk | driver expects). Reordering the controllers in the Qbus so that | the high-BR-level controllers were first in the bus solved the | problem in each case. | | Early Emulex QD21's (Q-BUS MSCP disk controller) were known to | use BR5. Revision E or F corrected it to BR4. APPENDIX G SECURITY ISSUES Unix uucp is notorious for being insecure by default. The paper "Uucp Implementation Description" by D. A. Nowitz says this: "The uucp system, left unrestricted, will let any outside user execute any commands and copy in/out any file which is readable/writeable by the uucp login user. It is up to the individual sites to be aware of this and apply the protections that they feel are necessary." In retrospect, this is understandable, as Unix uucp was originally developed to transfer arbitrary files and allow remote command execution in a completely-trusted environment (mail came a bit later, and news came much later). We were quite aware of uucp's history and reputation, particularly since many of the people who expressed interest in "uucp mail" for their VMS systems also expressed grave concerns over security issues. So, a prime goal of this project was to __ _______ make DECUS uucp as secure as possible by default -- that is, with no special action by the VMS system manager, and in spite of the lax security in effect on many (if not most) VMS systems. (VMS, for example, comes with just about everything set world readable; this may be fine within your shop, but you probably don't want your uucp neighbors reading your SYSTARTUP.COM, the SYSUAF.LIS files that you forgot to delete, and so on.) We believe we have achieved this; DECUS uucp should be secure even if you don't set up the directory and file protections we recommend, or even if you do something silly, like give the uucp login a system UIC. This was possible because DECUS uucp's prime job is to move mail and news, not to transfer arbitrary files. Of course, it does have to transfer files to move mail and news, but only between cooperating systems' spool directories. [1] We want you to trust this system to such an extent that you're willing to use it; so in the following sections we will describe in detail DECUS uucp's security provisions, and also 'fess up to ____________________ [1] With release 1.2 of DECUS uucp, we are providing a DCL-accessible uucp command, but it is restricted to files in the spool directory. SECURITY ISSUES Page G-2 a few problems. G.1 Decus Uucp Security Provisions G.1.1 Directory Access We have "hardwired" uucico.exe ("hamstrung" or "hobbled" might be a better term) to refuse to honor remotely specified device and directory specs ("path names" in Unix terminology). In all file specifications received from remote systems, it ignores anything to the left of a colon, angle bracket, square bracket, or slash (all of the delimiters we know of that separate Unix and VMS directory specifications from file names), and then prepends "UUCP_SPOOL:" to whatever's left. | | This explictly applies even to the uucp command, even if it's | installed with SYSPRV; files arriving from other systems will | always go to the spool directory, regardless of what the | initiating uucp command looked like. If someone sends us a file spec with a directory delimiter we don't recognize, the result will be a bad file spec (since we'll still put "UUCP_SPOOL:" on the front), not a file in some unexpected place. The worst anybody should be able to do is create an odd-looking file in the spool directory. This prevents uucp from being told to reconfigure itself (perhaps by someone sending you a new control file; sure, they can send you a file called CONTROL., but it will just sit in the spool directory and be ignored). It also prevents uucp from poking _____ around in other directories in the system (outside of the uucp hierarchy), which many system managers leave world-readable. ____ The only way to eliminate this restriction is by modifying the source and recompiling uucico. G.1.2 File Protection Masks In the chapters on uucp configuration, we stated that all executables, command procedures, and configuration files (which, for one thing, specify what the spool directory is) should be protected against write access by the uucp login and by other ___ users on your system. This is not necessary to prevent a neighbor from telling your uucp to reconfigure itself, since that is already accomplished by restricting uucico's copy in/copy out operations to the spool directory. It does, however, prevent other users on your system from reconfiguring your uucp system, or perhaps replacing uucico.exe with a version that lacks the directory restrictions. SECURITY ISSUES Page G-3 Decus Uucp Security Provisions G.1.3 Priviliges And MAIL.EXE Under VMS Version 5, the old MAIL image (which was installed with SYSPRV, among others) was split up into several pieces. One of them, MAIL.EXE, is not normally installed with privileges. But it needs SYSPRV in order to access the foreign mail protocol handler, so UUCP_SYSTARTUP reinstalls MAIL.EXE with SYSPRV. The same thing is necessary for any other package which uses the foreign mail protocol "hook". DEC has stated that, in order to use other such packages, installing MAIL.EXE with SYSPRV is appropriate and safe, as it only turns SYSPRV on when necessary. (It does not, for instance, have SYSPRV on when you SPAWN from the MAIL> prompt.) G.1.4 Why Is UUXQT.EXE Installed With SETPRV ? The sharp-eyed system manager will no doubt have noticed that UUCP_SYSTARTUP.COM installs the uuxqt.exe image with the SETPRV privilege (among others). This is necessary to enable incoming mail to be delivered in a "replyable" format. For this, our "uuxqt" must execute the DCL command MAIL/PROTOCOL, which requires the SYSPRV and DETACH privileges (and, under VMS Version 5, BYPASS). Captive account or no, hardwired directory names or no, we obviously don't want to give these privileges to the uucp login, or even to the image (uucico) run thereby, so we use the following roundabout method to let uuxqt do what it needs to do while uucico runs in a nonprivileged environment: o Uuxqt.exe is installed with SETPRV. It is started in a batch job by UUCP_SYSTARTUP, typically at system boot time. It spawns a subprocess running the DCL command procedure uuxqt_dcl.com, and then turns off SETPRV (and all other unneeded privileges). Now the subprocess has SETPRV, but the process running uuxqt.exe does not. o Uuxqt.exe hibernates while waiting for work; the dcl subprocess is in a local event flag wait (waiting for a read on a mailbox, to which uuxqt.exe will write). o When an X-file is received, uucico awakens uuxqt.exe (via a "doorbell" implemented with locks and blocking ASTs; this works across nodes on a cluster, whereas mailboxes and ordinary hibernate/wake do not). Upon being awakened, uuxqt searches for any X-files in the spool directory. For each X-file, it modifies any referenced filenames as described above (forcing the directory to UUCP_SPOOL:), and passes the X-file contents through the mailbox to the DCL subprocess. o The subprocess uses SETPRV to turn the needed privileges on just before executing rmail and rnews commands, and turns them off again immediately thereafter. SECURITY ISSUES Page G-4 Decus Uucp Security Provisions To summarize: The uucp login never runs any images installed with setprv, but only runs uucico. Uucico can only create files in the spool directory; uuxqt can only look for files in the spool directory; and uuxqt_dcl can only use those files to send mail or to bring news into the news database. As long as the uucp login cannot change UUXQT.EXE or UUXQT_DCL -- which is triply ensured; first, the uucp login has only execute access to these files; second, the uucp login does not have write access to the directory these files live in; and third, the only program that the uucp login can run, uucico, can't create files anywhere but in the spool directory -- the SETPRV privilege with which UUXQT is installed cannot be exploited. Note that uucico is installed also. The primary purpose of this is to guarantee that it has PRMMBX, SYSNAM (needed to create its permanent mailbox), and SYSLCK (needed to establish the remote hostname lock and to trigger uuxqt execution via the blocking AST mechanism). However, this also ensures that the installed images, uucico and uuxqt, were linked /NOTRACEBACK (since the INSTALL utility will reject attempts to install executable images ___ with privileges if those images were not linked with /NOTRACEBACK). The result of all this is that, even if the "captive account" mechanism failed and a uucp login "intruder" managed to get to a DCL prompt, the intruder could not activate either uucico or uuxqt and then use the debugger to exploit the privileges with which the image is installed. G.1.5 Privileges And Uucico To prevent problems that might occur if uucico is ever run from a privileged account, uucico explicitly turns off all unneeded privileges immediately upon startup. (See the sysinit() routine in sysdep.c. This is called from uucico.c's main() procedure.) G.1.6 "Remote Receive" Requests Disabled To send mail or news, the originating system tells the target, "I want to send these files". ("Originating" here refers to the immediate source of the mail or news, not to which system placed the phone call. Work, if available, is transferred in both directions during all calls.) Unix uucp also supports "receive" requests, as in "I want to receive file xyzzy.plugh". It is just barely possible that a malicious neighbor could inspect the sequence numbers of X- and D-files received legitimately from your system and send you "I want to receive" requests for D-files with "nearby" sequence numbers. Some of these will be D-files intended for other systems, so they would be able to read (and prevent proper delivery of) other people's mail. SECURITY ISSUES Page G-5 Decus Uucp Security Provisions We are considering fixing this in the next release by adopting an approach used in HoneyDanBer uucp: A different subdirectory of [.SPOOL] would be used for each neighbor system. For now, uucico will not honor "I want to receive" requests from other systems. You can change this by adding an entry to the control file (see the description of the control file in the chapter, "Configuring UUCP"). ___ G.2 Things They Can Do To You The preceding measures are sufficient to ensure that a system running DECUS uucp is "secure", to the extent that uucp cannot be used to either read or write files outside of the spool directory. This section describes a few things that a neighbor (or, more likely, someone -- referred to here as an "intruder" -- who learns the access information for your system used by one of ___ your neighbors) can do to you despite all of the above. The risk of username/password compromise can be reduced somewhat by enabling callbacks. This does not protect against the "wiretap" intruder; if they got the username and password off the phone line they can intercept the callback too. But it does help protect against the (presumably far more likely) case where the neighbor system manager just makes a mistake and leaves your access information where someone else can find it. G.2.1 Creation Of Files In The Spool Directory Neighbor systems can only create files in the spool directory, but they are not restricted to creating D- and X-files (the files used to send you mail and news). The file name can be anything desired as long as it's a valid VMS file name. For example, an intruder trying to probe your security might try to send you a new CONTROL. file. Or they might send you a "trojan horse" command procedure. If any command procedures, source files, or other "strange" files (anything, really, other than the regular uucp work files, B.*, ___ C.*, D.*, and X.*) ever appear in your spool directory, do not execute them or make them available to anyone else on your system. Inspect UUCP.LOG to see which neighbor system purportedly sent them to you (a DCL SEARCH command with the file name as the search target is all that's needed), and ask their _____ system manager what's going on. Have them check their log entries to see if they recorded a call to your system at the time indicated in your log. NOTE The appearance of such files is more likely to be evidence that your access information has been compromised than that your neighbor system manager is trying to do nasty things. Given that ___ assumption, it would be wise to not use uucp mail SECURITY ISSUES Page G-6 Things They Can Do To You for this inquiry. Another possibility is that an intruder might simply try to fill up the disk on which your spool directory resides. This is unlikely given modern disk capacities and the transfer speeds available over dial-up lines (even with Telebit modems), but if the prospect bothers you, you can always set an appropriate disk quota for the uucp login. G.2.2 Non-Direct Mail Is Not Private Remember that mail which does not go directly to the target site (with no intervening hops) is passing, in clear, through other systems, and that it may stay in those systems' spool directories for periods ranging from a few minutes to a few days. System managers and other privileged users can read files in the spool directories. Therefore, consider all mail sent to or from other than neighbor sites to be sent via a broadcast medium. G.2.3 Aliasing An intruder, by masquerading as your neighbor, might intercept outgoing mail which you intended to route through your neighbor, or might generate bogus mail to users at your site (making it appear as though it came from literally anyone on the net). Of course, with non-direct mail paths, this could happen anywhere on the net. (This problem is not specific to uucp mail; in fact, anybody on your system can generate mail with bogus From: lines by sending Mail-11 commands to the Mail DECnet object.) G.3 Contrast With Unix Uucp Unix uucp uses a "userfile", which controls which directories and files local users and remote systems can access, and a "commands file", which specifies which commands can be executed locally by remote sites. DECUS uucp does not have (and does not need) either of these, since it does not support arbitrary remote command execution and forces all remote file access to the spool directory. A subtle opening in Unix uucp/netnews security has to do with the map propagation scheme, as the maps are sent out in "shar" (shell archive) format. Many sites have an automatic procedure which extracts the new map entries from the newsgroup and executes them directly as "shell" (command language interpreter) scripts (command procedures). Obviously, a bogus map posting might contain shell commands intended to exploit whatever privileges are in effect when this is done. SECURITY ISSUES Page G-7 Contrast With Unix Uucp In DECUS uucp, the map entries are interpreted by special-purpose code; the worst that can happen in such a case is that the MAKEPATHS command procedure might generate invalid paths, or stop with an error message. G.4 The Internet Worm No discussion of computer security these days is complete without some reference to the infamous "Internet Worm" of November, 1988. We have analyzed the description of the worm (see "A Tour of the Worm" by Donn Seeley, reprinted in the Unix Systems SIG _____ ____ _______ ____ Newsletter that appeared in the DECUS U.S. Chapter SIGs __________ Newsletter for March, 1989, Vol. 4, No. 7, pages Uni-2 through Uni-20). None of the three security holes exploited by the worm are applicable to this uucp implementation, or to any other uucp for that matter. G.5 Uucp Security History Despite Unix uucp's requirement for an "active" security effort on the part of the system manager, the uucp network has been remarkably free of security problems. A small number of "aliased" mail and news messages have been posted; these have usually resulted in a public outcry on News and isolation (quarantine?) of the originating systems. Once the steps recommended in the Unix documentation are taken, Unix uucp is secure enough that many system managers publish their system's phone number and a username and password to be used for "anonymous uucp logins". (The usual purpose of this is to set up a "file library" from which large software packages may be distributed. Since the person who wants the software places the phone call direct to the "library", the library incurs no expenses for the transfer.) Because of the default security mechanisms built into DECUS uucp, we are confident that DECUS uucp, with no special action on the part of the system manager, is considerably more secure than Unix uucp -- even when all of Unix uucp's security features have been properly set up. APPENDIX H WANT TO HELP? This is a volunteer effort, and if you want to help out, we certainly want to encourage you to do so. However, we do ask ______ _______ __ _____ that you please contact us first. We are still working very actively on DECUS uucp; the code you have will almost certainly be an earlier version than what we are working with. If you go off and implement something without talking to us first, we'll try to incorporate it, but you must realize that: o We may already have done it, or o We may have thought about it and made provisions for doing it in a different way, or o We may already have done something else that precludes your implementation from working, or ____ o We may, for some other reason, have very strong requirements on how it needs to be done. If we can compare notes before you start, we can save everybody a lot of time, trouble, and aggravation. We really don't want to have to say "gosh, that's nice, but we can't use it", as this is not likely to encourage you to contribute again later. We'd much rather work with you beforehand! The following list provides style and design guidelines. o Local variables and function names should be in lowercase; globals (externals) should have their first character capitalized. Defined symbols should be in all caps. o We are not going to make any rules about brace/indent style, especially since the three of us each prefer a different one. If you create new code, pick a style you like and use it consistently. If you modify existing code, stick to the style that already exists in the routine(s) in question. WANT TO HELP? Page H-2 o Any event flags used should be allocated via LIB$GET_EF . Do not use LIB$FREE_EF to make any of the flags in cluster 0 available for allocation, or existing code which relies on the allocation of multiple flags from the same cluster will break. o Do not use the $HIBER/$WAKE mechanism within uucico, at least not while the packet protocol is running; use event flags instead. $HIBER/$WAKE is in use by the g protocol implementation. Having some other code thread do $HIBERs or $WAKEs while the packet protocol is running could cause it to fail. APPENDIX I CHANGES FROM VERSION 1.1 TO 1.2X 1.2A, 1.2B, and 1.2C changes are identified via appropriate prefixes. I.1 Example Configuration Files The command procedures which we expect you to modify as part of your installation procedure are now provided in a new subdirectory tree, [.EXAMPLES...] . For example, the supplied example control file is [.EXAMPLES.CFG]CONTROL. rather than [.CFG]CONTROL. ; no file called "CONTROL." is in [.CFG]. I.2 New Facilities I.2.1 UUCP Command A rudimentary uucp command is now provided. It will only be useful to privileged users, as it requires SYSPRV to run and we don't install it that way. (1.2B) The uucp.exe image would fail with an access violation if the logical UUCP_DOMAIN_NAME was not defined; this has been corrected. I.2.2 Utilities The following new utilities are provided: o MODATT -- examine, store for later use, and change file attributes. (This is Joe Meadows' FILE utility, under a different name.) o BATCHNEWS -- collect news from news directories into a news batch o DIFF and PATCH -- ported versions of public-domain Unix-like context difference and patch programs. CHANGES FROM VERSION 1.1 TO 1.2X Page I-2 New Facilities o ARBITRON and INPATHS -- collect readership and propagation data from your news data base for transmission to the Usenet research project at decwrl. (Invoked automatically by NEWSSKIM.) I.3 The Mailer I.3.1 Header Processing UUCP_MAILSHR now generates any headers that it does not find when processing a message. When processing a locally generated message, it assumes that no headers are present and generates them all. (A side effect of this feature us is that it fixes the problems caused when the first line of a message happened to look like an RFC822 format header, e.g. "Greetings:") UUCP_MAILSHR now processes and/or generates RFC 822 Message-ID's. A new header, X-VMS-Mail-CC, is now created for locally generated mail whenever VAX Mail passes the contents of the users "CC" input to UUCP_MAILSHR. As with previous versions of UUCP_MAILSHR, the X-VMS-Mail-To header is generated whenever VAX Mail passes the contents of the users "To" input to UUCP_MAILSHR. However, VAX Mail does not seem to always pass this information along. UUCP From_ line processing has been reworked. This should eliminate all known bugs with the handling of this header and improve compliance with Internet RFC 976. Also, in previous releases, From_ lines were discarded by the header processor. They are no longer deleted and will appear in the messages you receive. In UUCP_MAILSHR, the bug in parenthesis counting for RFC 822 From: lines has been fixed. (1.2A) The 1.2 mailer generated From_ lines containing DECnet-style addresses (node::user) for mail that originated on DECnet nodes other than the uucp node. This has been fixed in 1.2A. (1.2A) Recognition of the Message-Id: header is now case insensitive. (1.2A) Personal name text in RFC822 headers is now always enclosed in quotes, and imbedded quotes are escaped. (1.2A) Some Unix hosts running MMDF have been complaining about a "parse error" when processing the "From:" generated by the mailer. The problem appears to be caused when mail is sent from a user that has not defined a personal name. A strict reading of RFC822 indicates that in the absence of a personal name, the address should not be placed in "<>". For 1.2A, this is handled correctly. CHANGES FROM VERSION 1.1 TO 1.2X Page I-3 The Mailer (1.2A) A received message that contained a really ugly RFC 822 _ From: header caused UUCPMAILSHR to crash with an access violation. A short scratch buffer was located in the bowels of the address rewriter. The text of the From: was longer than the buffer causing the stack to become trashed. For version 1.2A the length of this scratch buffer has been changed to exceed the length of the text passed to the address rewriter. I.3.2 Logical Names (1.2A) For locally generated messages, UUCP_MAILSHR will look for the logical name UUCP_PERSONALNAME. If it is present, it will use its translation for the personal name field of the messages From address. If there is no translation, then NEWS_PERSONALNAME is tried. If neither one translates, then the personal name supplied by VAX Mail is used. This allows users to have different personal names for local and for network mail. (In 1.2, the order of search for these names was backwards.) It is no longer necessary (or desirable) to define the UUCP_DOMAIN_NAME logical if you do not have a registered domain. If UUCP_DOMAIN_NAME is not defined, or if the name ends in ".UUCP", From: addresses will be generated in "host!user" format instead of the "user@host.uucp" format that was previously used. I.3.3 Address Rewriting Pattern matching in the UUCP_MAILSHR rewriter is now case insensitive. Previously, the strings to be tested was forced to lower case, while the patterns from the rules file were left in their original case. Now, both the strings and the rules are forced to lower case before pattern matching is attempted. [INBOUND-FROM] rewrite processing has been enhanced slightly. Normally, when a message is delivered into your system, a "UUCP%" and quotation marks are added to the From: address. This makes the address replyable with the VAX Mail REPLY command. Now, if an [INBOUND-FROM] rewrite of the From: address results in a string that contains a foreign protocol selector -- such as IN% -- the address is passed on as is. This makes it possible to pretend that UUCP delivered mail arrived by some other means. (Note that the rewrite must return not only the foreign protocol selector, but the quotation marks in their normal positions for this feature to occur.) CHECKADDR (aka UUPATH) now supports the use of rewrite rules. This allows the rules to be tested without having to send mail and see what happens. (This was actually documented as existing in the V1.1 manual, but the code that was packaged with 1.1 did not support it.) CHECKADDR now creates two DCL symbols to reflect to the last path displayed. (It actually does it for all paths displayed, each display overwrites the previous values.) The symbol UUCP_PATH CHANGES FROM VERSION 1.1 TO 1.2X Page I-4 The Mailer contains the path that CHECKADDR displayed; UUCP_PATH_LENGTH contains the number of bangs ("!") in the path. Upon exit, a Success status code (%x10000001) reflects that a path was found; a Warning status (%x10000000) indicates that no path was displayed. I.3.4 File Names And Protection For the files that get transferred to a remote host, specifically the B and D files, UUCP_MAILSHR now creates names that are no longer than fourteen characters. It does this by truncating the hostname portion of the name whenever your hostname is longer than 7 characters. Both the filenames for the files stored in the local spooling directory, and the names passed to the remote host receive this treatment. This allows mail to be exchanged with older uucp systems that can't handle longer filenames, even though your uucp hostname might be greater than seven characters long. Files created by UUCP_MAILSHR in the spooling directory will now always receive a file protection of (S:RWED,O:RWED,G:RWED,W) regardless of the users current default file protection setting. (Formerly, if a user had set their default protection to System:No access, they could not use the uucp mailer.) In the UUCP spooling files created by UUCP_MAILSHR, the user identification fields now reflect that the files come from "uucp_daemon" at your host. Previous releases improperly placed From line information in these fields. I.3.5 Username Fields In B (X) Files (1.2A) The "U" line in "X" files contains the username and host which produced the UUCP request. Some UUCP systems, such as HoneyDanBer, use this information to determine which commands UUXQT may process. Some implementations appear to choke on a username longer than 8 characters. HDB as implemented under Xenix has been reported to have this problem. Versions of the mail handler prior to 1.2 generated all manner of interesting things for the "U" line. For 1.2, the behavior was _ changed to always generate "U uucpdaemon yourhost". For 1.2A, the mail handler will generate "U uucp yourhost" in the X file. I.3.6 MAKEPATHS MAKEPATHS may now be instructed to use more disk and less memory. See the commentary at the beginning of UUCP_BIN:MAKEPATHS.COM for instructions on how to set the UUCP_MAKEPATHS logical name to achieve this. CHANGES FROM VERSION 1.1 TO 1.2X Page I-5 The Mailer I.3.7 Help File For MAIL In [.DOC] you will find a help module, MAIL_UUCP.HLP, which may be inserted in your SYS$HELP:MAILHELP.HLB help library. (Courtesy of Kent Brodie) I.4 UUCP I.4.1 Protocol Handling During the uucp startup sequence ("shere exchanage"), we now ignore leading NULs when looking for strings starting with DLE and ending with NUL. This avoids a problem that shows up as "No ROK received" logfile messages on outbound calls. (This fix due to Todd Aven, manager@usgcdh.com) On incoming calls, we now send Shere=ourname instead of just Shere. Most uucps prefer the former, and all seem to be able to take it. On outbound calls, the timeout during the shere exchange is increased from 10 to 40 seconds, to give the answering system a ____ long time to get uucico going. BSD 4.3 uucp's send two null bytes before (after?) each packet. We no longer report these as errors in the log. (This fix due to Jerry Leichter, yale!lrw!leichter) We no longer increase the debug level after a number of errors have occurred. Allow for receipt of ACK while in CLOSE state, and for INITC in RUN state. This eliminates some spurious (benign) error reports. (1.2A) Comment lines delimited with either "#" or "!" may appear in the systems. file in the midst of continued entries. (1.2A) The uucico "Shere exchange" sequence will now accomodate certain Sun systems which apparently terminate their Shere, etc., messages with linefeeds rather than nulls. I.4.2 Call Requests And Decisions The progressive recall time calculation is modified to not give floating-point overflows after large numbers of failures and/or long failure intervals. (This fix due to Tom Allebrandi) Don't bump nfails in the stst file if calling the same system as before during the same scan of the systems file. Formerly, if you had 'n' entries for a given system, and uucico tried and failed to reach them using all 'n' entries, this would be counted as 'n' failures. It's now counted as just one. CHANGES FROM VERSION 1.1 TO 1.2X Page I-6 UUCP _ Messages written to the uucico daemon's mailbox (UUCPREQUESTS:) are now logged in the regular log file rather than the debug log. The "$READCTL" message which can be written to the uucico daemon's mailbox to force a new read of the control file, is now case insensitive. (1.2A) A fail interval of zero (either explicit, or from an entry such as Any,15,,) would previously cause a divide by zero exception; this has been fixed. (1.2B) Formerly, the uucico daemon would only perform "polling" calls if it was awakened by expiration of its "sleeptime" interval; it would not perform polling after being awakened by notification of an outbound work request (e.g. a user sending mail). Unfortunately, this meant that if work requests always arrived before the "sleeptime" had expired, no polling would ever be done. This has been corrected; neighbors can now be polled both upon sleeptime expiration and upon outbound work notification. I.4.3 Script Processing Allow for talking to systems that want us to log in with other than no parity. A default parity for the login script may be specified in the systems entry, and this default may be changed within scripts via new script commands (parity_even, etc.). iflat and ifnlat script statements allow scripts to do different things depending on whether the port is a LAT port or not. (1.2C) In previous versions, the script processor failed to match incoming strings if more than 127 characters, with one or more null bytes, arrived before the target string did. In other words, one had trouble finding "username" and "login" prompts when calling systems with long pre-login announcements, if this output included null bytes. This has been fixed. (The fix is due to Bruce Tanner, tanner@cerritos.edu.) I.4.4 Terminal I/O For outbound calls, if the port is a LAT port, do the right things regarding CONNECTing and DISCONnecting the port as far as the LAT box is concerned. While we're at it, log the LATserver's name and the port name. The infamous "hangup bug", which caused the uucico daemon to become "wedged" after terminating an outbound call, has been fixed. VMS Version 5 introduced a bug in the terminal driver such that SET TERMINAL/NODISCONNECT no longer did what we want it to, that is, clean up and exit our image at the end of an incoming call, even if the port was set to /DISCONNECT originally. The effect CHANGES FROM VERSION 1.1 TO 1.2X Page I-7 UUCP was that, at the end of a call, the "Disconnected" process would wait around for the reconnect timeout interval, sometimes with the lock for the remote system still held. We've worked around the problem. (This fix by Mark Pizzolato.) In the control file, a new option on "port" lines tells uucico to not change the port speed for outgoing calls. (Useful with Telebit and other modems that can run at various line speeds with a single locked host interface speed.) We now recommend using these modems with a locked interface speed for both inbound and outbound calls. Do an automatic typeahead buffer flush after hanging up the line on outbound calls. This avoids certain autobaud and "huh?-what?" problems that get started when the modem sends a burst of noise to the VAX when the VAX drops DTR. (1.2A) Uucico now refuses to talk to RTAnnn devices, since such devices do not support several of the required $QIO SETMODE functions. (1.2C) The above-described check for RT devices, and the code for checking for LAT terminals, did not work if the device had a cluster-style name (node$RTAnnn). The code has been corrected to use information from $QIO sensemode and $GETDVI to identify LAT and RT devices, rather than looking for strings in the device name. I.4.5 File Handling Add "~" to the list of characters we look for when stripping directory specs from file names received from other systems. When processing a C file, don't delete each file as we send it. Instead, make a list of files sent and then delete them all at once when (and only if) the whole C file is processed successfully. (This fix due to Mark Pizzolato) Make the few-characters-at-a-time output in log files readable the way it's supposed to be (not one character per line). When logging the other system's transmissions to us during the startup sequence, print a leading ` if the high bit is set. There were several conditions under which the uucico daemon would leave channels open to temporary files in the spool directory if a file receive failed. This has been corrected. (1.2A) Uucico and uuxqt will now correctly handle received X and D filenames (but no others) containing more than one period (.). CHANGES FROM VERSION 1.1 TO 1.2X Page I-8 UUCP I.4.6 Configuration Files "!" may now be used as welll as "#" as a comment indicator in the control file. I.5 NEWS The DECUS uucp distribution includes ANU NEWS Version 5.9C. APPENDIX J CHANGES FROM VERSION 0.2 TO 1.1 This appendix describes the changes that were made in DECUS uucp from the first released version, 0.2, to the second released version, 1.1. J.1 Name Changes J.1.1 Logical Name Prefixes And Directories The top-level directory is now called [UUCP] (you can change this via logical name assignments), and all logicals are now prefixed with UUCP_ rather than VMSNET_ . We shouldn't have to change them again because we have registered the facility name, "UUCP", and the corresponding logical name prefix and shareable image names, with Digital. J.1.2 Images The gnuucp.exe image has been renamed to uucico.exe, to better reflect its correspondence to the Unix program of the same name. J.1.3 Other Files Many files such as log files, debug log files, and data files have had their names "rethought" to better reflect their function and to reduce the number of keystrokes required to access them. J.2 Required Configuration Changes J.2.1 Control File Changes The "nodename" entry has been renamed to "hostname", to avoid confusion between the DECnet node name and the uucp host name (since this entry reflects the latter). The debug level is now interpreted as a bit mask, not a simple number. To make it easy to specify the bit mask, the number supplied in the control file can be specified in hex or octal as well as in decimal. CHANGES FROM VERSION 0.2 TO 1.1 Page J-2 Required Configuration Changes Several new items have been added to the control file. J.2.2 Systems File Format Change Entries in the systems file must be modified to include several new fields; also, the login script information (expect-send sequence) has been moved out of the systems file into "script files", to which the entries in the systems file point. J.3 New Features J.3.1 Operational Features J.3.1.1 The Mailer J.3.1.1.1 Name Change - To reflect the change in name of the entire software package, the mailer is now called UUCP_MAILSHR and is invoked via UUCP%. J.3.1.1.2 Not-a-neighbor Routing - The previous version of the mailer accepted pure uucp bang path addresses verbatim: Mail was always queued to the next hop, regardless of whether or not you communicate with that host. The result was that the mail sat in your spool directory forever. For this release, the router checks to see if the next host is one you communicate with. If not, it generates a route to the host, then tacks on the rest of the bang path from the address you specified. J.3.1.1.3 Smart-host - This version of the mailer supports the "smart-host" alias. If a smart-host alias is defined in your local routing data, and the router encounters an address it can't resolve, the message is passed on to the smart-host. The presumption is that the smart-host should be able to figure out what to do with the mail address. J.3.1.1.4 Local Delivery - The previous version of the mailer did not allow addresses which resolved to the local machine. When it encountered one, it refused to send the mail. This restriction has been removed. CHANGES FROM VERSION 0.2 TO 1.1 Page J-3 New Features J.3.1.1.5 From Header Format - The format of the "From:" header in the mail body has been changed. Previously, the format was user@host (Personal Name) Now, it is Personal Name Both forms are valid according to the Internet specifications (RFC-822). It is hoped that the new form will work better with mailers that have trouble with ()'s in the personal name. J.3.1.1.6 Accessing The Paths File - The mailer now enables SYSPRV before opening UUCP_DATA:PATHS. There is no longer a requirement to make that file world readable, though it really should not hurt anything if it is. J.3.1.1.7 LongUserName - In the previous version, when mail was sent out from a VMS account that had a full 12 character username, the username did not appear in the "From:" address. This is fixed. J.3.1.1.8 Rewrite Rules - The mailer now supports a limited amount of address rewriting. The primary purpose for this is to allow the host running DECUS uucp to be a gateway for a local subdomain or a DECnet network. Inbound addresses to the gateway can be rewritten into a form that is correct to achieve the target delivery. Outbound addresses can be rewritten to allow them to be replied to by hosts that don't know (or care!) about your local topology. J.3.1.2 News Integration We are supplying a complete set of command procedures and programs for integrating ANU News with DECUS uucp. The package can now exchange News with Unix sites using the preferred "compressed rnews" format. When maps are received in the comp.mail.maps newsgroup, they will be automatically placed in the [.DATA.MAPSRC] directory, and the local PATHS. database will be updated, all without manual intervention. CHANGES FROM VERSION 0.2 TO 1.1 Page J-4 New Features J.3.1.3 Call Time Control The systems entry can now specify the days of the week and times during those days when the remote system may be called. In addition, the format allows the specification of retry intervals; these are used to prevent too-frequent outbound calls. J.3.1.4 "On-Demand" Outbound Calls Uucico.exe (formerly gnuucp.exe) will now automatically awaken, search for outbound work, and (if call time restrictions permit) initiate the appropriate call when a user on the local system sends uucp mail. This can reduce mail forwarding latency if the normal sleep interval is long. J.3.1.5 Polling If desired, DECUS uucp can now automatically "poll" neighbor systems in the absence of local work destined for those systems. This is useful for neighbors which cannot originate calls. J.3.1.6 System-Specific Debug Levels The system file entry for each neighbor system may specify the debug level that is to be used during calls to and from that system. This value, if present, overrides that specified in the control file for the duration of the call (or call attempt) that uses the system entry in question. J.3.1.7 Improved Log Files Log file entries have been reformatted and made easier to read. More debug log options are available, and debug log options may be specified independently of one another (for instance, turning on option 9 does not automatically turn on all lower-numbered ones). When a neighbor system dials in, SYS$ERROR is directed to a file in the log directory. The contents of this file will sometimes provide clues in the event that uucico terminates abnormally during an incoming call. J.3.1.8 Login And Dialer Scripts The code that deals with autodialing modems and handles "expect-send" sequences for outgoing calls has been completely rewritten to use "script files". These are ordinary text files that reside in [.CFG] . Two scripts, DIAL.modemtype and HANGUP.modemtype, provide dialing and hangup instructions for modems, so it is now easy to add support for additional modem CHANGES FROM VERSION 0.2 TO 1.1 Page J-5 New Features types without modifying the source code. Another script, LOGIN.systype, is used to negotiate the login sequence for remote systems. The "systype" field is obtained from the entry in the systems file for the neighbor being called. Additional string parameters can be passed from the systems entry to the login script, so that one script can serve for many neighbor systems. J.3.2 Security Features J.3.2.1 Local Username Checking The systems entry for each neighbor system can now specify the uucp login which that system is supposed to use for calls to your system. When servicing an incoming call, DECUS uucp checks this against the actual username of the process, and rejects the call in case of a mismatch. J.3.2.2 Callback Support DECUS uucp now supports automatic callbacks. A "callback required" flag in the local systems file dictates that inbound calls from the indicated system are to be rejected, following which the local uucp system will call the neighbor back. This provides enhanced security in case an intruder learns the uucp login username and password used by one of your neighbor systems; if your systems entry specifies callback, the only result will be spurious calls on your part to that neighbor. If the remote system is also running DECUS uucp, symmetrical callbacks are allowed; that is, a pair of systems can specify callbacks for each other; DECUS uucp will recognize the returned call as a callback, and will not go into an "infinite callback" loop. J.3.2.3 Remote File Receive Requests Disabled Unix uucp supports both remote send and receive requests, although only sends are used for transferring mail (that is, each system tells the other "I want to send this file"). For mail transfer, only sends are used, so we have inhibited our implementation from responding to other systems' "I want to receive file foo.bar" requests. (This capability may be reinstated by adding a line to the control file.) J.4 Implementation Changes CHANGES FROM VERSION 0.2 TO 1.1 Page J-6 Implementation Changes J.4.1 Improved "g" Protocol Implementation The implementation of the "g" protocol now supports "windowing", and reads a reasonable number of characters at a time (not just one) from the serial port. The result is a dramatic improvement in throughput, together with an equally dramatic reduction in VAX CPU load, over the Version 0.2 implementation. J.4.2 New Execution Strategies In Version 0.2, the gnuucp image for placing outgoing calls was run in a self-resubmitting batch job; it attempted to place calls each time it ran. Its replacement, uucico, is still run in a batch job, but it is now designed to be started once (typically when the VMS system is started) and should run until the system is shut down. The image waits (rather than exiting) between each series of work scans. (In order to conserve physical memory, uucico purges its working set before entering the wait.) Similarly, uuxqt now "runs" continuously. Its batch job is started when the rest of the DECUS uucp system is started. After processing all available work (normally none at startup time), it hibernates rather than exiting, waiting for the next execution file to be received. This single uuxqt job processes all incoming work from all neighbor systems, rather than being invoked to handle work from a single call. The uuxqt process is awakened each time an execution file is received rather than once at the end of a call. This should result in greater overlap between uuxqt (which is mostly disk-bound) and uucico (which spends most of its time waiting for I/O on the serial link); peak disk space requirements will also be decreased. The process invoked by the MAKEPATHS procedure has been streamlined to improve CPU utilization and significantly reduce temporary disk storage. Previously, the output from the Pathalias route generator was sent to disk and subsequently postprocessed by three separate utilities. The three utilities have been replaced by a new utility, PathProc. PathProc attempts to do all of the postprocessing work in memory, and will only use temporary disk space if it runs out of memory. Further, PathProc will cause Pathalias to be run in a subprocess, with the output from Pathalias being fed directly to PathProc, using no intermediate disk space. (A working set of around 4K pages is required for efficient operation, however.) J.5 Bug Fixes The following problems were discovered in Version 0.2. These have been corrected in this release. CHANGES FROM VERSION 0.2 TO 1.1 Page J-7 Bug Fixes o The gnuucp and uuxqt images would abort with an access violation when running on a clustered system. (Corrected in sysdep.c) o The mail delivery mechanism for incoming mail failed under VMS V5 due to lack of sufficient privileges. (Corrected in uuxqt_dcl.com) o Uuxqt was sensitive to the name format of received X-files. (Corrected in uuxqt.c) o The "g" protocol had several problems communicating with certain types of Unix uucp's as well as the Telebit Trailblazer's implementation. (Gio.c replaced with giowvms.c) APPENDIX K ACKNOWLEDGEMENTS K.1 Version 1.2x As before, Jamie Hanrahan made a few changes to uucico and friends; Tom Allebrandi made improvements to UUCP_MAILSHR; and Mark Pizzolato tweaked the NEWS interface. Mark also wrote UUCP_CONFIG.COM . K.2 Version 1.0 And 1.1 Tom Allebrandi made many improvements to UUCP_MAILSHR (formerly VN_MAILSHR), allowing routing of bang-path addresses, and implemented the address rewrite mechanism essential for local subdomain support. He also wrote the PathProc utility. Jamie Hanrahan implemented the windowed g protocol, the dial/login script processor, and the new uuxqt execution mechanism. He (I) also did most of the writing for this manual. Mark Pizzolato wrote the new call scheduling and status recording code, and also created the programs and command procedures necessary to integrate ANU News and DECUS uucp. He also made several improvements in the character I/O performance of the non-windowing g protocol implementation of Version 0.2 and debugged several problems in its packet handling. None of the latter code survives in the current windowing version, but his work provided a great deal of information which was invaluable during the implementation and testing of the windowing code. Mark also got a modified Version 0.2 working with a Trailblazer modem and wrote the Appendix describing how he did it. Anyone who wants to understand windowed protocols is referred to ________ ________ Chapter 4 of the standard work on the subject, Computer Networks _______ _ by Andrew S. Tanenbaum (Prentice-Hall). Another book, Kermit, A ____ ________ ________ File Transfer Protocol by Frank da Cruz (Digital Press), provided a very lucid (dare I say "transparent"?) description of the sliding-window extension to Kermit. Although windowed Kermit differs in several important ways from uucp "g", this material was of great assistance in designing the windowed "g" implementation. ACKNOWLEDGEMENTS Page K-2 Version 0.2 K.3 Version 0.2 Tom Allebrandi is responsible for the port of pathalias and for the integration of smail with the VN_MAILSHR image. The UUCP Project authored the original smail, and Dr. Peter Honeyman created pathalias. Jamie Hanrahan worked on gnuucp, uuxqt, and rmail, and the documentation you're reading. (The occasional "I" that creeps into the text here refers to him. Me, that is.) VN_MAILSHR and rmail were derived from Kevin Carosso's uucp mail interface, as distributed on the Spring '87 DECUS VAX SIG tape. rmail has become a procedure called by uuxqt. Gnuucp and uuxqt are derived from John Gilmore's gnuucp package, with mods for VMS by Lol Grant. Jamie made some changes to the dialer code and to the uuxqt execution mechanism to get it to run well with dialup lines. The dialer code was taken from C-Kermit/VMS, and modified to work with VMS ports (many of which won't send you data until they see carrier, so it's useless to look for "CONNECT" strings). Credit is also due to Todd Aven, whose MAKE utility Jamie used, and to the original authors of the MFTU utility, which Todd distributed. (We used MFTU to transfer LZCMP'd backup savesets between Tom's and my machine via Kermit.) _____ A large round of applause goes to Bill Blue, proprietor of Crash Timesharing in El Cajon, California. Bill's machine (crash.cts.com) was (and still is) Jamie's primary "guinea pig" for testing gnuucp and mail. Bill spent many hours answering Jamie's naive questions and interpreting uucp log files after (numerous) failed attempts. It is no exaggeration to say that the VMSnet software would not be running today if it were not for Bill's assistance. Thanks, Bill! (Bill is also the uucp map coordinator for Southern California and Arizona, and the completeness and accuracy of the maps for this region are due largely to his efforts.) Bison, and the versions of gnuucp and uuxqt which appear in our [.ORIG_CODE] directories, are Copyright by the Free Software Foundation, and are made available under the terms of the GNU software license. The full text of this may be found somewhere in [.ORIG_CODE...]. Recipients of this software are asked to comply with its terms. These original versions of gnuucp and uuxqt were in turn based on a public domain program called "uuslave", author unknown. In the case of these programs, therefore, the GNU license only applies to the portions of the code written by John Gilmore. Our changes and additions to all of these programs are in the public domain.