.! standard beginning .page size 60,65 .! length,width .rm 65 .! width again .flags uppercase { .flags lowercase } .flags accept \ .flags underline _ .no flags bold .!flags bold % .flags hyphenate ` .flags break | .flags space ^ .flags period ~ .no flags capitalize .no flags overstrike .!flags overstrike < .no flags subindex .!flags substitute $ .no flags substitute .no autosubtitle .spr 0,1,2 .! change if indented paragraphs desired .ap .sthl 4,0,6,7,7,2,1,7,2 .! run-in heads at level 4, level 0 all caps .title DECUS UUCP Version 1.1 System Manager's Guide .subtitle .!date .!first title .! probably don't want first title .autosubtitle 1 .figure 14 .c;DECUS UUCP (VMSNET Software) .c;Version 1.1 .s .c;System Manager's Guide .s2 .flags substitute $ .C;$$month $$day, $$year .no flags substitute .c;(Spring 1989 Distribution) .s3 .c;prepared by .c;The VMSnet Working Group .c;DECUS VAX Systems SIG .s2 .no fill Jamie E\. Hanrahan^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^Tom Allebrandi II Simpact Associates^^^^^^^^^^^^^^Advanced Computer Consulting, Inc 9210 Sky Park Court^^^^^^^^^^^^^^^^^^700 Harris Street, Suite 101 San Diego, CA 92123^^^^^^^^^^^^^^^^^^^^^Charlottesville, VA 22901 +1 619-565-1865 x1116^^^^^^^^^^^^^^^^^^^^^^^^^^^^^+1^804-977-4272 jeh@crash.cts.com^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ta2@esther.acci.com .fill .S2 .c;Mark Pizzolato .c;1558 Fernside Street .c;Redwood City CA 94061 .c;+1 415-369-9366 .c;...!uunet!lupine!infopiz!mark .no justify .no autojustify .display number RL .page .figure 6 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 "@^DSR^USRGD10^/RIGHT=10" (the space preceding the slash is required) at the DCL prompt; this will produce a new .MEM file with the specified right margin. 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". 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!)~ .figure 3 VAX and VMS are trademarks of Digital Equipment Corporation. .br;Hayes is a registered trademark of Hayes Microcomputer Products, Inc. .br;Unix is, as we all know very well by now, a registered trademark of AT&T. .figure 3 THIS DOCUMENT IS IN THE PUBLIC DOMAIN. .page .require "usrgd11.rnt" .display number D .number chapter 0 .chapter Introduction Welcome to the second 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.1) is being prepared for distribution via direct mail and the DECUS VAX SIG Symposium tape for Spring, 1989 (Atlanta, Georgia). A previous version, 0.2, appeared on the Symposium tape for Fall, 1988 (Anaheim, California). This version of DECUS uucp supports both VMS^V4.7 and^V5. We expect to continue to develop and refine both the software and the documentation; future versions will appear on VAX SIG Symposium tapes, and once the software is somewhat stable it will be made available through the DECUS library, and by other means as appropriate. .hl 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[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. .end footnote 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. 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. 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. .hl 1 How To Get More Help Look in the map files for a nearby network site, call the person indicated, and tell them that you want a uucp connection to your VMS system, but that you'll need a bit of hand-holding. You have to contact these people anyway to arrange for mail and News transfer. (A later section will describe the map files in detail.) .hl 2 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[2]^^The publisher has expressed an interest in incorporating VMS-related material in future editions. .end footnote 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: .s .lm+8 .no fill O'Reilly And Associates 981 Chestnut Street Newton, MA 02164 1-800-338-6887 1-617-527-1392 (in Massachusetts) .s .lm0 .fill 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.) 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. .hl 2 Don't Call Us, At Least Not Very Often We really hate to have to say this, but we have to say this: .s .lm+8 .rm-8 WE, THE AUTHORS, CANNOT PROVIDE MUCH TELEPHONE SUPPORT FOR THIS SOFTWARE. .rm+8 .lm-8 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! .hl 1 On-Line Help If you do need to ask us for help, there are ways to contact us other than by phone. .hl 2 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. .hl 2 DECUServe You are urged to sign up with DECUServe, DECUS's dial-up on-line conferencing system.^[3]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[3]^^It is not the case that DECUS uucp is intended to compete with or supplant DECUServe. DECUServe provides many benefits which most sites will be unable to duplicate with uucp and News. For one thing, their policy is to save everything forever, while disk space constraints require most Network News sites to delete all material that's over a few weeks old. For another, DECUServe provides contact with a huge number of people who, for any of several reasons, can't use uucp. Finally, we see uucp and News as potentially complementing DECUServe, in ways which we can't talk about yet but which should be obvious. .end footnote 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. LN03 and Postscript versions of the DECUServe application form appear in [UUCP.DOC.SERVICES]DECUSERVE.LN3 and .PS^. (Note that these forms specify an annual fee of $45; an increase is planned for July^1, 1989, and the new amount has not been fixed at this time. If you try to join after that date you should obtain a new application.) If you don't have a printer compatible with either of these, send a note to .s .lm8 .no fill DECUS -- DECUServe Processing 219 Boston Post Road, BPO2 Marlboro, MA 01752-1850 .fill .lm0 and ask for an application. DECUServe's dialin numbers are in the Boston area, and are reachable via PC-Pursuit, so phone costs should not be prohibitive. .hl 2 "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. .hl 2 For More Help and Updates After It's Running Once you can send and receive network mail, send mail to .s .i8;VMSNET-REQUEST%FALCON@AAMRL.AF.MIL .s 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 .s .i8;VMSNET%FALCON@AAMRL.AF.MIL .s and they'll be relayed to everyone else who has signed up. If you have trouble with either of these addresses, try sending mail directly to Ted Nieland, the list's moderator, at .s .i8;TNIELAND%FALCON@AAMRL.AF.MIL .s or, if that fails, try .s .i8;TNIELAND@AAMRL.AF.MIL 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 one of the groups in our hierarchy is gatewayed to the list. .hl 1 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. .s .lm+4.rm-4 We can only correct problems which are reported to us! .lm-4.rm+4 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 WHAT'S NEW IN THIS RELEASE This chapter provides a brief description of the new features of this version of DECUS uucp. Readers who are familiar with previous versions of the software should read this to learn what changes they will need to make in order to use this version. .hl 1 Name Changes .hl 2 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. .hl 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. .hl 2 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. .hl 1 Required Configuration Changes .hl 2 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. Several new items have been added to the control file. .hl 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. .hl 1 New Features .hl 2 Operational Features .hl 3 The Mailer .hl 4 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%. .hl 4 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. .hl 4 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. .hl 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. .hl 4 From header format The format of the "From:" header in the mail body has been changed. Previously, the format was .lit user@host (Personal Name) .end lit Now, it is .lit Personal Name .end lit 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. .hl 4 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. .hl 4 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. .hl 4 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. .hl 3 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. .hl 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. .hl 3 "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. .hl 3 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. .hl 3 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. .hl 3 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. .hl 3 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 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. .hl 2 Security Features .hl 3 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. .hl 3 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. .hl 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.) .hl 1 Implementation Changes .hl 2 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. .hl 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.) .hl 1 Bug Fixes The following problems were discovered in Version^0.2. These have been corrected in this release. .ls1,"o" .le;The gnuucp and uuxqt images would abort with an access violation when running on a clustered system. (Corrected in sysdep.c) .le;The mail delivery mechanism for incoming mail failed under VMS^V5 due to lack of sufficient privileges. (Corrected in uuxqt\_dcl.com) .le;Uuxqt was sensitive to the name format of received X-files. (Corrected in uuxqt.c) .le;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) .els0 .chapter 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. .hl 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 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. .hl 1 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. There is no provision for user-requested file transfers (in other words, no "uucp" DCL command is included), nor for arbitrary remote command execution (no "uux" command either). 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. DECUS uucp's uucico is based on "gnuucp", written by John Gilmore. The "gnu" prefix on this name refers to the "gnu" operating system ("Gnu's Not Unix"), a project of the Free Software Foundation. (gnuucp in turn was based on "uuslave", a program which was found on a public-access bulletin board with no author's name attached.)~ .hl 1 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. 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. .hl 1 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.) .hl 1 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".) .hl 1 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 .s .i8;arisia.ge.com .s and a typical mail address is .s .i8;everhart@arisia.ge.com .s where "ge" is a company name and "arisia" is a machine at ge.^[1]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [1]^^Yes, this is Glenn Everhart, VAX SIG Tapecopy coordinator and member of the DECUS Library Committee. .end footnote 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [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. .end footnote 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 addressed via "Internet-style" names. .hl 1 ...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 will appear in {_The Matrix: Computer Networks and Conferencing Systems Worldwide}_ by John S\. Quarterman, scheduled to be published by Digital Press in June, 1989. (Order number EY-C176E-DP; $59.95 plus tax. Digital Press, DEC, 12 Crosby Drive BU0/E94, Bedford MA 01730 U.S.A. I highly recommend purchasing this.) .chapter INSTALLING THE FILES The files here should restore into [VAX8nx.UUCP...] (or [UUCP...] if you receive this distribution directly from the authors rather than from a VAX SIG tape). In most directories you will find a file called \_FILES.TXT . Each such file describes the files in the corresponding directory; in some cases, it also describes the underlying subdirectories. With your default set to [UUCP], TYPE [...]\_FILES.TXT will give you a complete guide to the tree. For all future references to the directories, we will assume that device:[UUCP] is the default. For example, [UUCP.BIN] will be referred to as [.BIN]. For convenience, we have included Geoff Huston's NEWS program in [.NEWS5n], though it is not part of DECUS uucp. (Not that we wouldn't be proud to call it that. But it's a significant and worthy effort on its own, and deserves to stand and be recognized by itself.)~ 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, 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. .chapter 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.) Others have successfully used previous versions of DECUS uucp with terminal servers, but we have no personal experience with this. All of the following information pertains to directly-connected serial lines. If anyone can provide detailed setup information for modems connected to terminal servers, we would very much appreciate being able to incorporate it here (with credit, of course!). .hl 1 Serial Line Configuration For typical modems, serial ports may be configured like those used for ordinary interactive dialins. Here is an example SET TERMINAL command such as might appear in your site-specific startup command procedure: .s .lm+8 .literal $ SET TERMINAL TXA1: /PERMANENT /AUTOBAUD /DISCONNECT - /MODEM /DIALUP /HANGUP /DMA /ALTYPEAHD - /SYSPASSWORD - /HOSTSYNC /TTSYNC /LINE_EDIT /DEVICE=VT100 .end literal .lm0 .s The qualifiers on the first two lines are required. (Dma and altypeahd aren't strictly required, but improve performance to such a degree and with so little cost that there is no point in not using them.) 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 qualifiers on the last line 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. (Actually, VMS automatically changes them back when the uucp process releases the serial line.) Variations of this setup are possible, and are sometimes necessary for certain modem types. See, for example, the Appendix on Telebit Trailblazer modems. .hl 1 Typeahead Buffer Size 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.)~ This will allow the remote system to send you a complete "window" of 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. 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. This change will have an utterly trivial effect on nonpaged pool usage (ten extra bytes will be allocated for each port set to /ALTYPEAHD). .hl 1 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 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). .hl 1 Modem 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. .note This issue is not specific to uucp. It applies to any modems used for interactive dialins and dialouts. .end note .hl 2 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". .hl 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.) .hl 2 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[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. .end footnote 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. 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. .if NOTYET An exit handler addresses this for the (hopefully very rare cases) where the uucico image exits unexpectedly with an access violation or other unexpected failure. .endif NOTYET 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.) .hl 2 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.) 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". .hl1 RS232 Control Signals VMS places stringent requirements on how the modem uses RS232 control signals. Uucp adds a few more requirements. In general, if you can use the modem for incoming calls, it is probably set up properly for uucp; but there are a few exceptions to this, as described below. .note These considerations are not specific to uucp, but apply to any modems and ports used for interactive dialins and dialouts. .end note .hl 2 Terminal Multiplexer Capabilities 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, 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. .hl 3 Notes for LAT Users We are told that at least some LAT ports, although they do the right things with modem control signals as far as the modem is concerned, do not make all of the signal states available for reading by applications in the VAX. This should not be a problem as long as your modem can return result codes to detect call progress. .hl 2 Modem Capabilities .hl 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. 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[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. .end footnote This makes outward dialing difficult, since it often takes longer than thirty seconds for carrier to be received (particularly with modems such as the Telebit TrailBlazer, which support nonstandard transmission modes). 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!) .hl 3 Data Terminal Ready (DTR) 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. .hl 3 Carrier Detect (CD) 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. .hl 3 Clear To Send (CTS) 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s .br;[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. .end footnote That is, if the modem lowers CTS, the VAX will (after a brief delay) stop sending data until the modem raises CTS. 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, uucp "g" protocol "spoofing", etc., the modem will on occasion need to tell the VAX to stop sending data for a moment. Since "inband" methods (such as XON/XOFF) are forbidden, CTS flow control must be used. Modems in this category include those which support upper levels of MNP, and the Telebit Trailblazer Plus in its uucp "g" spoofing or compression modes. An Appendix to this document provides information about the Trailblazer, which has become a de facto standard for high-speed uucp connections. If you have another type of modem which fits into the category described above, please read that Appendix anyway; it may not help you directly but it should give you some valuable hints. .hl 3 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), 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. Special considerations apply for the Trailblazer (again, see the relevant Appendix). Some modems (including the Trailblazer) 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; if present, this option must be disabled. .hl 1 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. .hl 1 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. .hl 1 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) 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.)~ .s .ls0," " .le;$ ALLOCATE TXA7 .le;$ SET TERM TXA7/SPEED=nnnn .le;$ SET HOST/DTE TXA7 .els0 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 .ls1," " .le;$ DEALLOCATE TXA7 .els0 .hl 1 Summary Here is a brief list of the requirements for uucp serial links. .ls1,"o" .le;Configure the VAX ports as you would for interactive dialins, but be sure to enable /ALTYPAHD and, if the terminal multiplexer supports it, /DMA. .le;Ensure that the TTY\_ALTYPAHD SYSGEN parameter is set to at least 210 bytes. .le;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. .le;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. .le;Ensure that your terminal port and modem correctly provide and interpret all of the required RS232 control signals. .le;Use a straight-through cable that connects at least pins 1 through 8, 20, and 22. .le;Test the modem with simple dialin and dialout operations. .le;If you are using a Telebit Trailblazer, refer to the relevant Appendix. .els0 .chapter ARRANGING FOR UUCP CONNECTIONS This chapter describes three "administrative" tasks which must be performed before you can begin configuring DECUS uucp. .hl 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 should be unique within the first seven characters; although the network can tolerate^-- barely^-- duplicate site names, life will be much simpler for you if your name is unique. Searching the map files in [.DATA.MAPSRC] is a good way to find out if your candidate name is already taken.^[1]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [1]^^Murphy's Law, as applied to the theory of supply and demand: "All the good ones are taken."~ .end footnote 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: .lm+8 .rm-8 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 and each section of the domain name must begin with a lowercase alphabetic and may {_not}_ end with a dash. .lm-8 .rm+8 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 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 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 .s .i8;sysname.orgname.com .s where sysname designates a machine within your company, 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 (see [.DATA.MAPSRC]README.). 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...)~ .hl 1 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. You can also get a connection to uunet, a system 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 dial-up lines (either using 800 numbers or regular long-distance), which all run Telebit Trailblazer modems, but also via a local call to a Tymnet PAD. If you don't have a nearby site that can give you a high-speed connection, Uunet can offer a real cost savings as well as good connectivity. Some information can be found in [.DOC.*]UUNET*.TXT . To get complete, up-to-date information and an application form, send your U\. S\. Mail address to .s .lm+8 .no fill UUNET Communications Services P.O\. Box 2685 Fairfax, VA 22031-0685 1-703-764-9789 .fill .lm-8 .s (While you're at it, ask them to send information on Internet domain registry as well.) 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; you shouldn't "do business" on other people's phone line time. (Uunet is obviously an exception to this, as they are collecting fees for their services, though only enough to recover costs.)~ .hl 1 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 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}_; see Chapter^0 for information.)~ .chapter CONFIGURING DECUS uucp This chapter describes how to set up DECUS uucp (and VMS) to communicate with neighboring systems. .hl 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. This account should be an ordinary nonprivileged account; it does not need NETMBX, but needs TMPMBX. 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 CAPTIVE, DISCTLY, DISMAIL, DISNEWMAIL, DISWELCOME, DISREPORT, and DISRECONNECT flags for the account. For now, set the DISUSER flag too. 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.) You can have just one uucp login, or you can have a different one for each site with which you exchange phone calls, plus another for the uucico batch job. We recommend the latter approach; it improves security and makes it easier to track uucp activity in the VMS accounting file. All of the uucp logins should have the same UIC (and therefore the same identifier). .note 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. (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). .end note 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. We have found it useful to create another uucp login with the same UIC and privileges, but with the 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. .hl 1 Define Logical Names Inspect the file [.BIN]UUCP\_SYSTARTUP.COM and edit it as indicated in the comments. 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. We do recommend that you read the whole file to see what we're up to. Then execute the command procedure with the parameter "LOGICALS", e.g.: .s.i8;@[.BIN]UUCP\_SYSTARTUP LOGICALS This parameter causes the procedure to only define the logical names, some of which are needed in the next step. .hl 1 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). .hl 2 Create Your 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. .note You'll find a file called U.simpact in the map source directory; this is simpact's "live" map entry at the time this document was prepared. You should move U.SIMPACT out of the [.DATA.MAPSRC] directory before running MAKEPATHS (described in the next step). U.SIMPACT is provided as an example, but if present, MAKEPATHS will find it and incorporate it into your routing database. .end note Note also that you should not place lines like .s.i8;esther = .esther.acci.com or .s.i8;simpact simpact.com in your map entry unless you are actually registered as an Internet domain (that will come later). .hl 2 Building PATHS. When your map entry is complete, you can build the "compiled" map file, [.DATA]PATHS. , which is read automatically to process outbound mail. To do this, enter either of the following DCL commands: .s.i8;$ @UUCP\_BIN:MAKEPATHS .s or .br.i8;$ 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. .note If you ever modify [.DATA]PATHS\. by means other than running MAKEPATHS, ensure that the result is a streamlf file. .end note .hl 2 Obtaining Current Maps Regardless of how you obtain this package, the maps that come with it will be a little out of date. 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 in a single "shar" file. (This is easy, since all they have to do is tell their news program to write all of the articles in comp.mail.maps to a single file; the maps are posted to news in "shar" format.)~ They can transfer the "shar" file to you on magtape, either in Ansi format (which you can read directly with the DCL COPY command) or on a Unix-style "tar" (tape archive) tape. Programs for reading and writing "tar" tapes under VMS are in [.BIN]; the documentation is in [.DOC.UTILS]. To use the "shar" file, place it in a newly-created temporary directory, set your default there, and enter the following command: .s .i8;$ @[.BIN]UNSHARMAPS shar\_file\_name This will "unpack" the shar file and change the file names as appropriate for VMS. (The map file names on Unix have multiple periods in them; we change every period except the first to a hyphen.)~ When all of the maps have been extracted, COPY or RENAME all the files in the temporary directory (except the shar file!) to [.DATA.MAPSRC], PURGE [.DATA.MAPSRC], and delete the temporary directory. 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. .hl 1 The Control File The {_control}_ file establishes parameters used by several parts of the uucp system; both uucico and uuxqt read it upon startup.^[0]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [0]^^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. .end footnote This file is supplied in example form in [.CFG]CONTROL.EXAMPLE^; this is simpact's "live" control file. Please print a copy of this file before proceeding. All finished? Sorry, but we'll be doing a lot of that. There is just too much information to incorporate here. .note In the [.CFG] directory you will also find, in addition to the files described in this chapter, files with names of the form MAIL\_REWRITE.RULES\_*^. Ignore these for now. (The software ignores them too; they're examples.)~ We'll talk about them in the chapter on Internet Domain Registry. .end note .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. .end note 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. There is no explicit provision for comments, but lines with unrecognized keywords are simply skipped, so if you want to add comment lines with leading !'s or #'s or even "commentline", that's fine. 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. .hl 2 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. .end note .hl 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.^[1]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [1]^^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. .end footnote 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.) Note that we said "maximum" time: The daemon will also be awakened (via a mailbox message) whenever anyone sends outgoing uucp mail. When awakened for this reason (as opposed to expiration of the sleeptime interval), the daemon will attempt to call only those systems for which outgoing work exists, even if polling is enabled for other systems. .hl 2 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. .end note 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 example systems file (see the next section). .hl 2 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: .s .lm+8 .literal port .end literal .lm-8 .ls1,"o" .le;As shown in the supplied example file, "port" is a literal string. .le; 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. .le; 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 and [.CFG]HANGUP.HAYES . Scripts are described in detail in the next chapter. .le; 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) support. 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.) .els0 .hl 2 Enbrmtrcv If you want to allow Unix 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: .s .lm+8 .literal enbrmtrcv 1 .end literal .lm-8 .s 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]^. .hl 2 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: .s .i8;$ COPY SYS$INPUT UUCP\_REQUESTS: .i8;$READCTL .i8;\^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.)~ .hl 1 The 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.) 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 [.CFG]SYSTEMS.EXAMPLE^; 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. 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 or #'s may be used to denote comment lines, and these may appear in between the lines of a single entry. 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, processing continues with the next entry, and the call decision is made according to that entry's fields. (See also the description of the part of the field, below.) 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. The format of each entry is: .s .literal \ \ ... .end literal 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. .hl 2 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.)~ .hl 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. .hl 2 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. .hl 2 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. .hl 2 field may be \`-' (as a placeholder) or one or more of: .s .lm+8 c^^^^^^callbacks required .br;xn^^^^^set the debug level to n .lm0 The c option indicates that, when the remote system calls in and logs in, uucico will not go ahead with the call but will instead hang up and call the system back, as a security feature. 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 x option sets the debug mask. 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 .s .i8;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. .end note .hl 2 field The when string indicates when calls may be placed to the remote system. It takes the following form: .s .i2;[ssss-eeee][\|[ssss-eeee]...][,succ[,fail[,poll]]] .s The brackets (angle and square) denote syntactic elements, and should not appear in the actual file. Square brackets denote optional elements. .ls1,"o" .le; is a string consisting of one or more of the following day codes, all run together: .s .i8;Su Mo Tu We Th Fr Sa Wk Any Never .s "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.)~ .le;[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. .els0 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 (,). .ls1,"o" .le; 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. .le; 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. .le; 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 has work, for the remote system, relying on the other system to call in if it has work for your system. .els0 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. 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: .s Any .s.lm+8 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 four hours, but if the last contact with them failed, retry every five minutes (scaled by 1.5 for each additional failure) until we get through. No polling will occur. .s .i-8;Any1800-2200 .s 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. .s .i-8;Wk1700-0600\|SaSu,240,60,1440 .s 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. .lm0 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 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. (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.^[2]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [2]^^This hint came from the book {_Managing uucp and Usenet}_ (see Chapter^0). .end footnote When setting up a new connection, it is reasonable to use a field such as the following: .s .i8;Any,0,0 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 0 fail interval will not cause uucico to retry immediately and forever, as the minimum "automatic" interval is set by the daemon sleep time.) .hl 2 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, you can invent a special port name, and add one or more "ports" entries to the control file accordingly, specifying the physical devices to which those modems are connected. .hl 2 field is the line speed to use when calling the system. 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". .hl 2 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. .hl 2 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 description of the script language. .hl 2 ... fields are optional string parameters, available to the login script.^[3]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [3]^^And to the dial and hangup scripts, for that matter, though they are typically only used with the login script. .end footnote 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 \\-. .hl 1 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 and Telebit Trailblazer modems, and logins for VMS and Unix systems). 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: .hl 2 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. Two dial scripts, DIAL.HAYES and DIAL.TBGSPOOF, are provided; these have been tested with Hayes-type modems and with Telebit Trailblazer modems in g protocol "spoofing" mode, respectively. .hl 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.CRASH\_EXAMPLE^. .hl 2 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 the Telebit Trailblazer.)~ .hl 1 Summary Here is a brief list of the steps required to set up uucp's configuration files: .ls1,"o" .le;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. .le;Edit and run the startup file to create the UUCP\_ logical names. .le;Create your "uucp map entry", and run MAKEPATHS to create the path data base. .le;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. .le;Create one or more entries in the systems file for each of your network neighbors. .le;Review, and modify as appropriate, the supplied dial, login, and hangup script files. .els0 .chapter 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [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". .end footnote 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. .hl 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 "expect". 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: .ls1,"o" .le;One of the actions may cause a transition to another state, in which case the rest of the current state's actions are skipped. Processing resumes with the first action statement of the new state. .le;If none of the actions cause a state transition, and there are no expects in the state, processing "falls through" to the next state in the file. .le;If none of the actions cause a state transition, but there are expects in the state, the state machine pauses until one of the expects is "satisfied". It then transitions to the state named in the expect statement. .els0 Finally, there are two action statements which, when executed, cause the script to exit. .hl 1 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. .hl 2 Action Statements .hl 3 Termination and informational statements .lm+17 .spr-17,1,2 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. .lm0 .spr0,1,2 .hl 3 Sending data .lm+17 .spr-17,1,2 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 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). .lm0 .spr0,1,2 .hl 3 Special terminal control statements .lm+17 .spr-17,1,2 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.) .lm0 .spr0,1,2 .hl 3 Counting, branching, and testing statements .lm+17 .spr-17,1,2 sleep^^^int^^^^^^delay for i milliseconds. zero^^^^^^^^^^^^^clear the counter. count^^^^^^^^^^^^add one to the counter. ifgtr^^^ns^int^^^go to state ns if counter greater than i. 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 i {_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. .lm0 .spr0,1,2 .hl 2 Expect Statements Expect 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". .note We have, no doubt unfortunately, used the word "expect" for both a particular statement and for the class of statements which includes {_expect}_, {_timeout}_, and {_ifcarr}_. In the narrative, we will differentiate between the two by underlining the word {_expect}_ to refer to the statement; the unadorned word refers to the statement class. (Alternatives for the class name are hereby solicited!) .end note .lm+17 .spr-17,1,2 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. 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 i 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. .lm0 .spr0,1,2 .hl 1 Script Processing Details .hl 2 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: .s .lm+8 .literal \d EOT character (control-D) \N null character \n line feed \r carriage return \s space \t tab \- hyphen \\ backslash \ooo character with value ooo (in octal) .end literal .lm 0 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). .hl 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. .hl 2 "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 dial script may specify other substitutions (see below). .hl 2 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". .hl 2 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. .hl 2 Overriding Defaults The script processor sets several default values. The following statements, which override these defaults, may be useful in certain circumstances. .lm+17 .spr-17,1,2 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. 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). .lm0 .spr0,1,2 .hl 1 Written Any Good Scripts Lately? If you come up with any new script files, please send them to us. The old dialer code (which the script processor replaces) supported many different modem types; in the rush to get Version^1.0 ready for the Spring '89 DECUS Symposium we decided to not try to create dial scripts for all of them, especially since none of us have any of the modems in question available for testing. The Hayes and Trailblazer scripts will satisfy many sites' needs, but as for the rest... if you get DIAL.RACAL-VADIC, DIAL.VENTEL, etc., running, please send them in! 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 Finishing and Testing The Installation of UUCP .hl 1 File Protection The uucp login UIC should own the [UUCP...] tree. Set all files in the tree to S:RWED, O:RWED, G:RWED, W:RE, and all directories to S:RWE, O:RWE, G:RWE, W:RE, except as noted below. The uucp login UIC, and {_all other users on your system other than those with system UICs}_, should be denied write or delete access to the [.BIN] and [.CFG] directories and to the files within them. Note that the uucico and uuxqt programs are "hardwired" to never create or look for files outside of UUCP\_SPOOL in response to requests from remote systems, so a neighbor system can never tell your uucp system to reconfigure itself, ship you a uucico image that lacks the directory restrictions, send you a control file that says that the control file is to be found in the spool directory, etc., etc., whether or not you set the file protections we have recommended. The intent of setting file protections is to prevent the other users on {_your}_ system from reconfiguring uucp, and thereby allowing it to give your system away. Regardless of how much you trust your users, [.CFG]SYSTEMS\. and [.CFG]LOGIN.* should not be world-readable, as these files contain access information for your uucp network neighbors. This is common courtesy to your neighbor system managers. (You expect them to similarly protect your system's access information, right?)~ The best way to protect the systems file is to set its owner to a system UIC, set an ACL on it granting read access to the uucp login, and deny access to all other users. "World" should be denied {_any}_ access to [.SPOOL] and [.DUMP], so that your users can't read other people's mail. 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. All tests with DECUS uucp have used the standard VMS default file protection (S:RWED, O:RWED, G:RE, W). You may encounter problems if your system uses a different default. You probably don't want to change your system default for the benefit of uucp; one fix is to place the following command as the first line in UUCP\_LOGIN.COM^: .s .i8;$^SET PROTECTION=(S:RWED,O:RWED,G:RE,W) .note This is one area that has not been tested extensively; that is, we are not certain that we've written down everything necessary to allow the various parts of uucp to access the files it needs to run. If you encounter problems related to file protections, please let us know so that we can revise the documentation. .end note .hl 1 Start It Up Take a deep breath, turn off the DISUSER flag in the uucp login accounts, and execute UUCP\_BIN:UUCP\_SYSTARTUP. It will: .ls1,"o" .le;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. .le;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. .le;Submit the UUCP\_CLEANUP batch job for execution one hour later (this will resubmit itself every hour). .els0 .hl 1 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: .s.i8;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. .hl 1 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: .s .i8;$ @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. .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). .end note 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: .s .i8;$ 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. .hl 1 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 it 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. .hl 1 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. If you have a "fortune cookie" type of program^-- one that displays a randomly-|selected witty saying when your users log in or out^-- add the following to its database: .lm+5 You are in a maze of twisty uucp connections, all alike. You are in a maze of twisty uucp connections, all different. You may have mail. .lm0 .hl 1 Tell The World Mail a copy of your map entry to: .s .i8;uucp%"rutgers!uucpmap" 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. .hl 1 Tell Us {_Please}_ send mail to one (or all) of the VMSnet team. 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) .hl 1 Adding More Neighbors Soon you will probably want to add more neighbor systems. Here is a checklist of things to do: .ls1,"o" .le;Create a uucp login for the new neighbor. .le;Exchange phone numbers, usernames, passwords, and other access information with the neighbor system manager. .le;Add one or more entries to your systems file. .le;If an existing login script isn't suitable, create an appropriate one. .le;Test the link by sending mail to a known user on the neighbor system, or by "bouncing" mail through the neighbor back to yourself. .le;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. .els0 .chapter 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. .hl 1 Why Should I Become a Domain? There are several good reasons for becoming an Internet domain. .hl 2 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.)~ .hl 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". 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. .hl 2 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.)~ .hl 1 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 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 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. .hl 1 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. .end note 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): .ls1,"o" .le;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}_. .le;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. .els0 .hl 1 What Then? Okay, you've sent off your application form and received confirmation that your new domain is active. Now what? .hl 2 Update Your Map Entry The "#N" line in your map entry stays the same. Add a line of the following form: .s .i8;#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 .s .i8;uucpname^^^^.yourcompany.com .s and .s .i8;uucpname^=^^machname.yourcompany.com .i8;uucpname^=^^yourcompany.com .s 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. .note The file [.DATA.MAPSRC]README. is not entirely up to date on these points. .end note .hl 2 Change Logical Names In [.BIN]UUCP\_SYSTARTUP.COM, change the definition of UUCP\_DOMAIN\_NAME to reflect your name. .hl 2 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: .s .i8;user@aridus.megacorp.com .i8;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.) .hl 2 Set Up The Mail Address Rewrite File .hl 3 Overview 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. Two example rules files are included in [.CFG], one for site esther.acci.com, and one for bi1.simpact.com^. Do {_not}_ use these files as-is! Print them out and study them while reading this section, and use them as a basis for your own rules file. .hl 3 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: .hl 4 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, an inbound-to address of the form "ta2@marty.acci.com" might be rewritten as "marty!ta2" since marty is connected to the "acci.com" domain via uucp. "jeh@dcs.simpact.uucp" can be rewritten as "dcs::jeh" since "dcs" is connected to "simpact.uucp" via DECnet. .note The "To:" header in the message body is NOT processed by the mail address rewriter. .end note .hl 4 Inbound-From The "From" address in an inbound message can be rewritten. You might use this to repair problem addresses by converting them into a form that can be replied to. For example, many older uucp mailers write "From" addresses in the form "host!user". The expectation is that hosts that subsequently handle the mail will add themselves to the "From" address in order to allow the mail to be replied to. This is not a valid expectation most of the time. If such addresses are giving you a particular problem, an inbound-from rewrite can be employed to try and fix this up. .hl 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. For example, from "esther.acci.com"'s point of view, mail to the "nodak.edu" domain on BITNET would normally be put into BITNET at the University of Virginia (uucp hostname "virginia"). Virginia, however, does not pass the message's "From" address in such a way that "nodak.edu" can reply to it. Uucp host "uunet", on the other hand, does handle the "From" address correctly, so an outbound-to rule has been employed to modify any addresses targetted at "nodak.edu", such that "uunet" and not "virginia" acts as the gateway to BITNET. 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. .hl 4 Outbound-From Outbound from rules are intended primarily as 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. .hl 3 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. .hl 4 Comments If a line begins with a "#", it is a comment and will be ignored. .hl 4 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): .ls1,"o" .le;[INBOUND-TO] .le;[INBOUND-FROM] .le;[OUTBOUND-TO] .le;[OUTBOUND-FROM] .end list 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. .end note .hl 4 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. .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 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. .end note 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: .s .i8;*!* \002@\001.my.domain .i8;*::* \002@\001.my.domain .s 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: .s .i8;marty!ta2^^^^^==>^^^^^ta2@marty.my.domain .i8;monica::ta3^^^==>^^^^^ta3@monica.my.domain .s 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: .s .i8;*@marty.acci.com^^^^^^marty!\001 .i8;*@esther.acci.com^^^^^\001 .i8;*@acci.com^^^^^^^^^^^^\001 .i8;*@*.acci.com^^^^^^^^^^uucp\_postmaster .s 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. .note Warning! The rule .s .i8;*!* \002@\001.my.domain .s 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. .end note .hl 1 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [2]^^The situation would be much the same if its connection to the world was via uucp. .end footnote 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 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.) .hl 1 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 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 goldstein@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. .hl 1 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 Administrative Tasks for News Support 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]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. .hl 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. .hl 2 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: .s .spr-26,1,2 .lm+26 comp.mail^^^^^^^^^^^^^^^^^technically you only need comp.mail.maps (to keep your map files, and therefore PATHS., up to date), but 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. .software.b and .software.notes can be eliminated if necessary. .lm0 .spr 0,1,2 The following groups are quite optional, but have proved valuable: .s .spr-26,1,2 .lm+26 comp.sources.misc comp.sources.unix .spr 0,1,2 .lm0 A surprising percentage of these sources are usable under VMS (assuming you have the VAX C compiler). .hl 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: .s .lm26 .spr-26,1,2 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 vmsnet.mail.pmdf^^^^^^^^^^gatewayed to info-pmdf vmsnet.misc^^^^^^^^^^^^^^^discussions of VMSnet itself (gatewayed to the vmsnet mailing list, vmsnet%falcon@aamrl.af.mil) vmsnet.sources^^^^^^^^^^^^source code postings for VMS systems (including VMSnet and ANU News-related software) vmsnet.sources.d^^^^^^^^^^discussions and requests for same vmsnet.sources.games^^^^^^recreational software (optional) .spr 0,1,2 .lm0 .hl 2 Others .hl 3 Telebit Newsgroup If you are using a Telebit Trailblazer 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.)~ .hl 3 "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). .hl 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. .hl 1 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. Initially you will have to get the VMSnet groups from another VMSnet site; send mail to one of the VMSnet developers (see the front cover) for a recommendation. Eventually many sites in the existing Unix community will likely carry the VMSnet groups, but that will not happen immediately. 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 uunet. (In fact, this is one of the primary main reasons that a lot of sites subscribe to uunet.)~ Uunet is committed to carrying the entire Usenet hierarchy plus all "alternate" hierarchies, so if you like you can get all your news from them^-- except, for now, for the VMSnet newsgroups. (Uunet shouldn't have any problem with carrying VMSnet; we simply haven't set it up yet.)~ .hl 1 Feeding News to Other Sites Obviously, if most sites accepted News and refused to pass 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). .hl 1 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [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. .end footnote is Version^5.7, as received from Geoff Huston, with a few slight modifications in the directory organization. Also, we have applied several bug fixes received from the net to the News source files and recompiled them. 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. We'll describe all of the files, the directory organization, and so on, in the next chapter. .hl 1 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. .end note .hl 2 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. .hl 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. .hl 2 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. .hl 2 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. .hl 2 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. .hl 2 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"). .hl 2 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. .hl 1 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. .hl 2 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). .hl 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 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.) .hl 2 Combinations News can be set up with some newsgroups kept locally and others "served", ie accessed on another machine via NNTP. .hl 2 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. .hl 1 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. .chapter Installing and Integrating News This chapter will tell you how to set up the ANU News 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. .end note .hl 1 The ANU News Distribution If you obtain ANU News from another source it will come in "its own" directory tree, [NEWS57...]. (At least, that's how we got it!)~ If you get it with DECUS uucp, it's in [UUCP.NEWS57...] instead, mostly because it's more convenient for us to distribute a single directory tree. More details on the [.NEWS57] tree will follow. .hl 1 Documentation ANU News comes with a very complete User's Guide, which also includes some installation and setup instructions. Most of this chapter is devoted to supplementary material for the latter. At this point you should look in the directory [.NEWS57.DOC]. This contains the User's Guide in three forms, Scribe, LaTeX, and line-printer format. We have LaTeX, so I have processed the LaTeX version to produce NEWS.DVI and NEWS.LN3. Even if you don't have the LaTeX software, you can print the latter on an LN03 equipped with at least one optional RAM cartridge (or equivalent, such as an LN03-Plus). If you have other TeX-suitable printers and corresponding "DVI" programs, you can process NEWS.DVI through the DVI program to get an appropriate printable file. (See your local TeXpert.)~ The News User's Guide is 175^pages long, at least in the LaTeX version. NEWS.LPT is presumably Scribe output (from NEWS.MSS and several "lower-level" files). It appears to be printable on a standard printer (I do hope you have one that produces lower case), but comes out mostly double-spaced. NEWS.DOC is a "standard printer" version that does {_not}_ come out double-spaced. Before proceeding, print whatever version of the News User's Guide (henceforth called the NUG) you can, read Chapters^1 through^5 and^7 through^13 thoroughly, and skim Chapter^6. (Relax; Chapter^6 is the bulk of the document, 120^pages.) .hl 1 Installing News: Comments on Chapter^10 of 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.)~ Chapter^10 in the NUG, "Installing News", provides some step-by-step instructions. The following sections amount to "release notes" for this material, based on actual installation experiences. The subsection headers below reference the names and numbers of the corresponding sections in the NUG. .hl 2 Installing News Files (NUG 10.1) 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. The subdirectory names we received in our copy of News^5.7 were different from those described in the NUG; further, we have divided things up a bit: .ls1,"o" .le;The User's Guide, which (as described above) is the major part of the documentation, as mentioned above, is in [.NEWS57.DOC]. .le;The "build" directory was called [.NEWS57.BLD]. We have divided this into two parts, [.NEWS57.BLD\_V4] (objects generated under VMS Version^4.7, with the VAX^C compiler Version^2.5) and [.NEWS57.BLD\_V5] (objects generated under VMS Version^5.0-2, with the VAX^C compiler Version^3). (Technically the V4.x sources would work under V5, but we wanted to get the benefits of the new^C compiler's improved optimization strategies.) .le;The "dist" directory was called [.NEWS57.DIST]. We have divided this into three parts, [.NEWS57.DIST\_V4] (executables generated under VMS Version^4.7), [.NEWS57.DIST\_V5] (executables generated under VMS Version^5.0-2), and [.NEWS57.DIST\_COM] (everything that was originally in [.DIST] except the executables). .le;Some additional information appears in text files in [.NEWS57.DIST\_COM], and this directory also contains samples for the News configuration files, which we will be editing in later steps. Print out all files in [.NEWS57.DIST\_COM] {_other than}_ NEWS.HLB . 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. .le;An additional directory, [.NEWS57.FIXES], is provided in the DECUS uucp distribution. This contains a number of bug reports and fixes which have appeared on the network since News^V5.7 was released. All fixes described have been applied to the source files in [.NEWS57.SRC], and the objects and executables described above were built with the "fixed" sources. [.NEWS57]AAAREADME.UUCP describes a few other changes that were needed under the new C compiler. .le;The actual compilation and link procedure is driven by [.NEWS57.SRC]NEWSBLD.COM. In both [.NEWS57.DIST\_V4] and [.NEWS57.DIST\_V5], an additional command procedure, NEWSBLD.BAT, is provided. This is an "envelope" which allows NEWSBLD.COM to be run as a batch job. .le;If NEWSBLD.COM finds evidence that the Wollongong TCP/IP (WINTCP) software has been installed on the system, it will define a symbol so that the NNTP TCP/IP support within News uses WINTCP instead of the default (CMU TCP/IP). We have WINTCP on our system, and the compilation attempt failed, so some minor changes were made to NEWSBLD.COM to allow suppression of this feature. NEWSBLD.BAT supports this option. (See the comments in the command procedures.) .els0 .hl 2 Compiling and Linking NEWS (NUG 10.2) As mentioned above, News is supplied compiled and linked under both V4.7 and V5.0-2. You should not need to duplicate these steps unless you want to provide support for Wollongong TCP/IP (WINTCP), and are prepared to trace down and fix the compilation errors which I encountered when I tried to do that. If you do want to rebuild it, create the directories [.NEWS57.DIST] and [.NEWS57.BLD]. Copy either [.NEWS57.BLD\_V4] or [.NEWS57.BLD\_V5] to [.NEWS57.BLD]. Make whatever changes you wish to the source files, then submit NEWSBLD.BAT to your favorite batch queue. NEWSBLD.COM will only compile those objects dated earlier than their corresponding sources, so if you want to force a rebuild of the whole package, delete the object files and libraries from [.NEWS57.BLD] before starting the job. NEWSBLD.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 NEWSBLD.BAT's existence); it doesn't matter what your default directory is when you submit it. NEWSBLD.BAT will also work fine interactively. When the build is done, the new executables will be in [.NEWS57.DIST], along with a new copy of NEWS.HLB. Inspect NEWSBLD.LOG to ensure that no errors occurred. (Remember that "undefined symbols" are reported by the Linker only as warnings; they will {_not}_ abort the link or inhibit the generation of the image file. This usually causes an access violation if you try to execute the resulting code.)~ When you're satisfied with the results, you can delete the corresponding .EXE and .HLB files that were supplied with the distribution. .hl 2 NEWS Accounts (NUG 10.3) 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. As noted in the NUG, this account requires SYSPRV. 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. We strongly advise you to put this account in the same UIC group as the "uucp login" account(s), perhaps with a different member number. All of our testing has been done in this environment; some file protection problems may occur if things are set up differently. 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^: .s .i8;$^SET PROTECTION=(S:RWED,O:RWED,G:RE,W) .hl 2 Logical Names (NUG 10.4) The referenced file, SETUP\_LOG\_EXAMPLE.COM, appears in [.NEWS57.DIST\_COM]. A different version, customized for the DECUS uucp distribution and with several extra features, appears in [.NEWS\_MGR]NEWS\_SYSTARTUP.COM (which is directly analogous to [.BIN]UUCP\_SYSTARTUP.COM). Ignore SETUP\_LOG\_EXAMPLE.COM and edit NEWS\_SYSTARTUP.COM as appropriate for your site. Following is a description of some of the logical names defined in this file. .hl 3 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, [.NEWS], under [UUCP], so that we would only have to distribute one root directory. You can of course make NEWS.DIR a UFD, or move it to another disk, or whatever; just change 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: .s .lm+8 .no fill $ defsysconc UUCP\_DEVICE UUCP\_DISK:[UUCP.] $ defsys NEWS\_ROOT UUCP\_DEVICE:[NEWS] $ defsysconc NEWS\_DEVICE UUCP\_DEVICE:[NEWS.] .fill .lm-8 .s 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.) .hl 3 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. .hl 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. .hl 3 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [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. .end footnote .hl 3 NEWS\_ADDRESS This should translate to the same name as UUCP\_DOMAIN\_NAME , and the supplied command procedure performs this translation automatically. .hl 3 NEWS\_NODE This is {_not}_ (usually) the DECnet node name of the system, 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. .hl 3 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 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]. .hl 3 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. (Note that while News correctly generates the header spelled with a "z", the logical is spelled with an "s", since Geoff Huston lives in Australia.) .hl 3 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. .end note .hl 3 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. .hl 3 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. This completes the customization of NEWS\_SYSTARTUP.COM . You may now execute the procedure to define the logical names, e.g. .s .i8;$ @[.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 it to redefine the logical names. .hl 2 Global DCL Symbols (NUG 10.5) [.BIN]USERCMDS.COM defines the NEWS symbol as .s .i8;$ NEWS == "$NEWS\_ROOT:NEWS" Accordingly, copy the appropriate version of the image NEWS.EXE to this directory ([.NEWS] in the DECUS uucp distribution). 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. .hl 2 Installing NEWS.EXE (NUG 10.6) This step may be performed via the command .s .i8;$ @[UUCP.NEWS\_MGR]NEWS\_SYSTARTUP INSTALLS .hl 2 Initial Environment (NUG 10.7) .hl 3 Creating the NEWSMANAGER identifier The "users who will be responsible for the management of News" probably means you, at least in the short term. Assuming that you have retained the names NEWSMGR for the "News manager" account created in the "second step" (Section 10.2), and "NEWSMANAGER" for the identifier, issue the following commands to the Authorize utility: .s .i8;UAF> ADD/IDENTIFIER NEWSMANAGER .i8;UAF> GRANT/IDENTIFIER NEWSMANAGER NEWSMGR .i8;UAF> GRANT/IDENTIFIER NEWSMANAGER yourusername .hl 3 Creating the directories These directories, as named by the appropriate logicals, already exist under [UUCP]. Ensure that [.NEWS] is set to world:re and system:w. (If you want to restrict access to News, you can apply propagating ACLs to the news root directory or to the appropriate subtrees of the news database. News also has a built-in system for restricting access to certain newsgroups; see the NUG.) DECUS uucp defines another special directory used for News-related log files. This is [.NEWS\_LOG] in the DECUS uucp distribution. The "news manager" UIC should have write access to and should own these directories. .hl 3 Setting Mail Forwarding for "USENET" "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. 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: .s .i8;MAIL> SET FORWARD/USERNAME=USENET yourusername You can of course achieve the same result with a logical name assignment. .hl 3 Copy NEWS.HLB to NEWS\_ROOT NEWS.HLB appears in [.NEWS57.DIST\_COM]. The HELP command {_within News}_ expects to find its help library in NEWS\_ROOT:NEWS.HLB. The source file, NEWS.HLP, is in [.NEWS57.SRC]; you may wish to review it and make site-specific modifications (or, if you didn't restore the sources, use the DCL LIBRARY command to extract and replace the modules you want to change). .hl 2 News Control Files (NUG 10.8) In this step we create the control or configuration files used by News. The sample files provided with News^5.7 are in [.NEWS57.DIST\_COM]^. 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [3]^^In the NUG, NEWSSKIM.COM is described as residing in NEWS\_ROOT. We have changed this in the DECUS uucp distribution. .end footnote Accordingly, in the DECUS uucp distribution, there is a similar set of these files in [.NEWS\_MGR]. (the translation of this logical as shown in NEWS\_SYSTARTUP.COM). 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 [.NEWS\_MGR], not those in [.NEWS57.DIST\_COM]^. 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. .hl 3 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^. Note that I (simpact) am set up to take just about everything, and also to feed everything I get back to scubed. But my news feeds only send me what I've asked for (so far, anyway), so I didn't bother making my filter set very elaborate. Note that if a site does send you news for groups that you don't want, News, by default, will ignore it if the groups have not been created on your machine. 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. In fact, you can copy this entire entry from simpact's file. The file name (MAPSAVER.TXT in simpact's file) can be anything. (Files of this name are created in the named directory, [UUCP\_MAPS]. The NEWSSKIM batch job processes {_all}_ files found in this directory, regardless of name, as map data, and then deletes them.)~ The next three entries are for esther, putz, and infopiz, my neighboring VMSnet sites, which is to say that I send them the VMSnet hierarchy, but no others. (They have more efficient ways to get the rest of the News.) Scubed is where I send my outbound News for everything outside of the VMSnet set. Note that I also {_get}_ news from crash (actually I'm converting from crash to scubed, and until the conversion is complete I'm getting some news from each), but I needn't do anything special in this file to allow for that. So I can't say "get these groups from scubed, and these other groups from crash". It doesn't matter; if I get the same message from both sites, or lots of sites, all copies will have the same message ID, and News will reject all but the first to arrive. Each site should be explicitly enabled to receive the newsgroup "to.hostname". 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 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 .s .i8;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: .ls1,"o" .le;(empty), e.g\. [POST\_SITE1], means send via DECnet .le;"DECNET\_", e.g\. [POST\_DECNET\_SITE2], means send via DECnet (same as previous) .le;"UUCP\_", e.g. [POST\_UUCP\_SITE3], means send uncompressed news via uucp to the "rnews" program on the target system .le;"UUCP$CMPRS\_", e.g. [POST\_UUCP$CMPRS\_SITE4], means send {_compressed}_ news via uucp to the "rnews" program on the target system .els0 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: .s .i8;$ 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: .s .i8;$ CREATE/DIRE NEWS\_MANAGER\_DEV:[UUCP\_MAPS] Ensure that the "news manager" owns and has write access to all of these. .hl 3 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. Simpact's file looks a little strange because two of the systems with which we exchange news, scubed and crash, aren't even mentioned. That's correct in this case because we are an "end node" {_as far as all newsgroups obtained from those sites are concerned}_. We needn't route crash's news to scubed, or vice versa, because both of them are far better connected than we are. We do specify a fully-connected interchange between ourselves and our "VMSnet" neighbors. The NEWS.SYS file will ensure that we don't try to send these folks anything other than the VMSnet hierarchy. 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.) .hl 3 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. .hl 3 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 [.NEWS\_MGR]) is substantially different from that in [.NEWS57.NEWS\_DIST]; {_ignore}_ the latter version and use ours. .end note You will probably not need to make any changes in this file. Two possible exceptions: .ls1,"o" .le;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:". .le;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".)~ .els0 .hl 3 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. .hl 3 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). .hl 3 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. .hl 3 Other files Several other files are supplied in [.NEWS57.DIST\_COM]: .ls1,"o" .le;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. .le;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 Section^5.2 of the NUG. This file should be placed in a public directory and made world readable. .le;NNTP\_FEED.COM is used to forward News to other sites via the NNTP protocol, via DECnet, CMU TCP/IP, or WIN TCP/IP. .le;The functions of the following files are incorporated in DECUS uucp's version of NEWSSKIM.COM. Accordingly, these files may be ignored: .s .br;NEWSADD.COM^^^^^^^^^^NEWSDAILY.COM .br;NEWSPACK.COM^^^^^^^^^NEWSSKIM\_ALT.COM: .els0 .hl 2 First Time Execution of News (NUG 10.9) .hl 3 Startup Double check everything, then from an account with SYSPRV, enter: .s .i8;$ @UUCP\_BIN:USERCMDS .i8;$ NEWS NEWS will respond with .s .i8;NEWS - create new ITEM file .i8;NEWS - first time installation... .i8;VMS NEWS V5.7 - 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 .s .i8;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. .end note .hl 3 Creating "control" and "local" Enter the following commands at the NEWS> prompt: .s .i8;create group control .i8;create group local 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. .hl 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] there are two files, CHECKGROUPS\. and CHECKGROUPS\.INET, which are copies of the most recent "checkgroups" postings as of this writing. The latter is only applicable if you will be receiving newsgroups in the "inet" hierarchy; your Unix news feed will be able to give you details on this. What you want to do is produce a file in this same format which reflects only those newsgroups you want to carry. Select the appropriate CHECKGROUPS file and copy it to MYGROUPS.TXT, then edit it 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 .s .lm+8 .no fill Newsgroups: news.admin.ctl,control Distribution: local Approved: spaf@cs.purdue.edu Subject: cmsg checkgroups Control: checkgroups .s !mod comp.ai Artificial intelligence discussions. comp.ai.shells Artificial intelligence applied to shells. (Moderated) ^^^^^^^. ^^^^^^^. ^^^^^^^. talk.rumors For the posting of rumors. .fill .lm0 .s 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 VMSNETGRPS). 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 .s .lm+8 .no fill to.myhostname messages from neighbors .fill .lm0 .s The file GROUPS.MINIMUM reflects the (almost) minimum set of groups you will likely want at first; you may decide to use this as-is. Again, remember that you can always add and delete more groups later on. When you are satisfied with your first version of MYGROUPS.TXT, you can invoke NEWS again, and at the NEWS prompt type: .s .i8;NEWS> ADD FILE MYGROUPS.TXT 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. .s .i8;$ @MYGROUPS.COM This will create the newsgroups you have requested.^[4]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [4]^^By default, groups are created with a default item retention period of thirty days. You can modify this with the SET NEWSGROUP command. In particular, you will probably want to set the retention period for comp.mail.maps down to seven days or so. 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. When you are confident that everything is working right you can trim the retention period for comp.mail.maps even further, perhaps to three days or so. .end footnote NEWS is now ready to accept these newsgroups from your news feeds. 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. .hl 1 Exchanging News with Other Sites (Batch Transfers) .hl 2 DECnet Transfers The method used for DECnet transfers is as follows: .ls1,"o" .le;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. .le;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. .le;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.) .els0 For this to work, the following conditions must be met: .ls1,"o" .le;News must be set up as described here on all machines in the network. .le;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. .le;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. .le;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. .le;If news received from other sites is to be sent to the DECnet node, appropriate entry(ies) must exist in NEWS.DISTRIBUTION^. .le;The NEWSSKIM batch job must run periodically on all machines. .els0 .hl 2 UUCP Transfers (both to Unix and to VMS) Ignore Section^13.2 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: .ls1,"o" .le;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. .le;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. .le;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. .le;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. .le;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. .els0 For this to work, the following conditions must be met: .ls1,"o" .le;News must be set up as described here on all of the VMS machines in the network. .le;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. .le;If news received from other sites is to be sent to the uucp host, appropriate entry(ies) must exist in NEWS.DISTRIBUTION^. .le;The NEWSSKIM batch job must run periodically. .le;You must have a uucp connection to each of the systems you're sending news to (as described in NEWS.SYS). .els0 .hl 2 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: .ls1,"o" .le;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). .le;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). .els0 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. .hl 2 Feeding News via NNTP We have no experience with this. Section^13.1 of the NUG has the basic information. There is also a command procedure, NNTP\_FEED.COM, which apparently provides this function, but is not mentioned in Section^13.1. There is also the 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. .hl 2 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? .hl 1 NNTP Client/Server Support Some information on this is in Chapter^12 of the NUG. We have no experience with using News in this fashion, and so can provide no additional information. 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!). .hl 1 Start Up the Transfer Processes Submit the NEWSSKIM batch job for periodic execution. You can do this by invoking the startup procedure as follows: .s .i8;$ @NEWS\_MGR: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: .s .i8;$ @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 Using the Telebit Trailblazer Plus The Telebit Trailblazer Plus has become a de facto standard for high-speed links in the uucp world. Besides its "ordinary" high speed, error correcting capabilities, it offers 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 9600^bps 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 Trailblazers "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 have on occasion reached 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 modem with DECUS uucp.^[1]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [1]^^This material is based very closely on an article Mark Pizzolato wrote for posting to netnews, earlier this year. .end footnote (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.) .hl 1 Hardware Requirements The setup to be described assumes that the VAX serial port to be used implements full modem control, {_including the Clear To Send signal}_. Such ports include: .ls1,"o" .le;All ports in the DHV11, DHQ11, DHU11, DMB32, DMZ32, CXY08 .le;Ports 0 and 1 on the DMF32 .le;The DB25 serial port on the MicroVAX 2000 .els0 All ports on the DZ11, DZV11, DZQ11, CXA16, CXB16, DZQ11-CR, and ports 2 through 7 on the DMF32, provide partial or no modem control. The TrailBlazer will not work as described below with these ports. .hl 1 Goals We have several seemingly contradictory requirements. We want: .ls1,"o" .le;To be able to initiate uucp outbound calls at a speed appropriate for the modem being called; .le;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"; .le;To allow callers to dial in at a speed appropriate for the modem they were using and dynamically autobaud to their speed; and .le;To be able to call some Trailblazers that answer with PEP tones last, but still establish a PEP connection. .els0 The solution is to use a locked interface speed (at 19,200 bps) for incoming calls, allowing the modem to answer at the speed of the calling modem and take care of the speed difference between that and the VAX, while setting the interface speed to whatever is desired for outbound calls. 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; we take care of this by using hardware flow control (using the CTS signal) to throttle data going from the VAX to the modem. No flow control is needed in the other direction because we're going the "other way"^-- from a lower-speed line to a higher-speed line. We also need to comply with the other requirements detailed in the chapter on "Modems and Multiplexers", but this is not difficult with the Trailblazer. .hl 1 Modem Settings Here are the settings that are different from the factory defaults: .ls1,"o" .le;Q6^^^^^^^^^^Return result codes only on outgoing calls. .le;X3^^^^^^^^^^MNP & PEP extended result codes enabled. .le;S51=254^^^^^Autobaud outgoing calls, assume 19200 on incoming. (This is not documented in my version of the manual.^-- MP) .le;S52=2^^^^^^^Reset to EEPROM values on DTR drop. .le;S53=2^^^^^^^DSR ON only when DCD is ON. DCD is ON when carrier is detected. .le;S54=3^^^^^^^Pass BREAKs transparently. .le;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). .le;S66=1^^^^^^^Lock interface speed. .le;S68=2^^^^^^^Use hardware flow control: CTS is turned off by the modem when it wants to stop the flow of data to it, and turned on when the modem can accept data. .le;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. .le;S110=1^^^^^^Data compression is enabled provided the connection is made in PEP Mode and the modem at the remote end also has data compression enabled (S110 equals 1 or 255). .els1 The odd-looking part is S66=1 and S51=254, and the flow control settings S58=0 and S68=2, but it works. .hl 1 Setting it Up Here's the full procedure for getting a brand-new TrailBlazer working with your VAX under DECUS uucp. We assume that it's connected to a "Full Modem Control" serial port (DHV11, DHQ11, DHU11, DMF32, etc.) named TXA0:. .ls1 .le;Set up the port attributes somewhere in the system startup files with the following command: .s .no fill $ SET TERMINAL TXA0: /PERMANENT/SPEED=19200 - ! needed ^^^^^^/MODEM/HANGUP/DIALUP/ALTYPEAHD^^^^^^^^- ! needed ^^^^^^/DMA/SYSPASSWORD/TTSYNC/HOSTSYNC^^^^^^^^! optional .fill Note the explicit setting of /SPEED verses /AUTOBAUD. We do {_not}_ recommend trying to use a Trailblazer without using the alternate typeahead buffer; further, the SYSGEN parameter TTY_ALTYPAHDSZ should be set to {_at least}_ 210 (up from its default of 200).^[2]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [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 Trailblazer for "normal" interactive logins to other computers with Trailblazers. The Trailblazer'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. .end footnote .le;Connect to the modem using: .s .no fill $ ALLOCATE TXA0: $ SET TERMINAL/SPEED=9600 $ SET HOST/DTE TXA0: .fill .s and then type the following: .literal AT &F Q6 X3 S51=254 S52=2 S53=2 S54=3 S58=0 S66=1 S68=2 S92=1 S110=1 &W .end literal That should be all on one line; it's wrapped here for readability. 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 .s AT &N .s to display the modem's settings. .le;Exit back to DCL with \^\\ (that is, Ctrl-Backslash) and release the modem port: .s $ DEALLOCATE TXA0: .els0 Now that your modem is configured, it should be usable with DECUS uucp connections at any speed. On outbound calls, uucico sets the speed of the serial port as indicated in the systems entry, and the modem autobauds on the "AT" Hayes wakeup sequence. For inbound, the modem answers at the speed of the modem placing the call, and does the necessary speed conversion between that and 19200. .hl 1 Control and Systems File Entries The supplied file [.CFG]CONTROL\. shows such a modem on TXA0: .literal port ACU hayes txa0: 2400 port ACU tbgspoof txa0: 19200 .end literal 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 Trailblazer modems are connected! .hl 1 Compatibility Issues While debugging this, Mark Pizzolato found a bug in the Trailblazer'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 TrailBlazers 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. 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 Pathalias (Uucp Map File Format Details) The following material is adapted from the "manual page" for Unix pathalias(1), written by Dr\. Peter Honeyman. .hl 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. .hl 1 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 connections consists of a {_from}_ host in column 1, followed by white space, followed by a comma-separated list of "to" hosts, called {_links}_. .hl 2 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. 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. .hl 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). .end note .hl 2 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: .literal 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) .end literal 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. Some examples: .literal down princeton!(DEDICATED), tilt, %thrash(LOCAL) princeton topaz!(DEMAND+LOW) topaz @rutgers(LOCAL+1) .end literal 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. .hl 2 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 .literal seismo (10), research(100), ihnp4(10) research allegra(10) ihnp4 allegra(50) .end literal 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.) .hl 2 Aliases The set of names by which a host is known to its neighbors is called its {_aliases}_. Aliases are declared as follows: .literal name = alias, alias ... .end literal 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. .hl 2 Networks Fully-connected networks, such as the ARPANET or a local-|area network, are declared as follows: .literal net = {host, host, ...} .end literal The host-list may be preceded or followed by a routing character, and may be followed by a cost: .literal princeton-ethernet = {down, up, princeton}!(LOCAL) ARPA = @{sri-unix, mit-ai, su-score}(DEDICATED) .end literal The routing character used in a route to a network member is the one encountered when "entering" the network. See also the sections on gateways and domains. .hl 2 Hidden Hosts Connection data may be given while hiding host names by declaring .literal private {host, host, ...} .end literal 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. .hl 2 Preventing Routing Through Certain Hosts, Links, or Networks Dead hosts, links, or networks may be presented in the input stream by declaring .literal dead {arg, ...} .end literal where {_arg}_ may be any of: .ls1,"o" .le;A single host name. The host is treated as dead and is used as a relay host of last resort on any path. .le;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. .le;A network name. Such a declaration indicates that the network requires a gateway. .els0 .hl 2 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 .literal CSNET = {...} csnet-relay CSNET .end literal then routes to CSNET hosts will use csnet-relay as a gateway. .hl 2 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: .literal harvard .EDU # harvard is gateway to .EDU domain .EDU = {.BERKELEY, .UMICH} .BERKELEY = {ernie} .end literal yields .literal ernie ...!harvard!ernie.BERKELEY.EDU!%s .end literal Output is given for the nearest gateway to a domain. For instance, the example above gives .literal .EDU ...!harvard!%s .end literal Output is given for a subdomain if it has a different route than its parent domain, or if all its ancestor domains are private. .hl 2 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, add a line like .lit smart-host = host .end lit to your local map file. (Do not include this line in the map entry when you mail it to the uucp mapping project.)~ 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, rather than blithely assuming that they won't mind routing all of your site's mail. .end note .hl 1 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: .literal rutgers princeton!topaz!%s@rutgers .end literal 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." .hl 1 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 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. .page .hl 1 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][rf] [file] .lm+8 .spr -6,0,2 +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: .s .i8;tail -40f barney .s 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. .lm-8 .spr 0,1,2 The following is a useful way to use tail with the uucp log file: .s .i8; $ tail -20f 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. 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. .page .hl 1 Compress .hl 2 Synopsis .lm+8 .literal compress [ -c ] [ -d ] [ -f ] [ -v ] [ -p ] [ -z ] [ -b bits ] [ filename ... ] uncompress [ -c ] [ -v ] [ -p ] [ -z ] [ filename ... ] zcat [ filename ... ] .end literal .lm-8 Unix shell-style I/O redirection (>, <, >>, \|) and background processing (&) are supported. .hl 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. .hl 2 Options .lm+8 .spr -8,0,1 -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 "#! cunbatch\n" while compressing, and strips (and requires) this prefix from a file being uncompressed. Used for sending (compressing) and receiving (decompressing) news. -z^^^^^^Leave name unchanged and don't impose or require "-Z" file names. filename ... .br;Files to be compressed. If none specified, stdin is used. .spr0,1,2 .lm0 .hl 2 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. .lm8 .spr-8,1,2 Usage: compress [-fvc] [-b maxbits] [file ...] .br;Invalid options were specified on the command line. Missing maxbits .br;Maxbits must follow -b. "file": not in compressed format .br;The file specified to "uncompress" has not been compressed. "file": compressed with "xx" bits, can only handle "yy" bits .br;"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 .br;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)? .br;Respond "y" if you want the output file to be replaced; "n" if not. uncompress: corrupt input .br;A SIGSEGV violation was detected, which usually means that the input file is corrupted. Compression: xx.xx% .br;Percentage of the input saved by compression. (Relevant only for -v.) -- not a regular file: unchanged .br;When the input file is not a regular file, (e.g\. a directory), it is left unaltered. -- file unchanged .br;No savings are achieved by compression. The input remains uncompressed. .spr 0,1,2 .lm0 .hl 2 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. .hl 2 References "A Technique for High Performance Data Compression", Terry A. Welch, "IEEE Computer", vol. 17, no. 6 (June 1984), pp. 8-19. .page .hl 1 Uurate - Report Transfer and Connect Times for Uucp Calls .hl 2 Synopsis .i8;uurate [-s] [-c] [-h hostname] logfile ... logfile .hl 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. .hl 2 Options .lm+8 .spr-8,1,2 -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 .spr0,1,2 .lm0 .hl 2 Example Output .hl 3 Example 1 .literal $ 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: 3 executions of rnews 3 executions of rmail .end literal .hl 3 Example 2 .literal $ 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 .end literal (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.) .hl 2 Notes Uurate is run automatically once a day by the UUCP\_CLEANUP batch job. The resulting report is mailed to UUCP\_POSTMASTER. .hl 2 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 Address Formats This appendix provides a brief introduction to the construction and use of network addresses. .hl 1 The Simple Cases .hl 2 How Do People Send Mail To Me? Until you are registered as an Internet domain, you can tell people that your network address is .s .i8;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 .s .i8;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: .s .i8;\{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. 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. .hl 2 How Do I Send Mail Out? For most {_site}_s, you will be able to respond to the VMSmail "To:" prompt with .s.i8;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 .s .i8;remhost!user you can generally use a VMSmail "To:" address of .s .i8;UUCP%"user@remhost" If you get something in the more complex form shown previously, .s .i8;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 .s .i8;\{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 .s .i8;UUCP%"wkh2!theirhost!user" .hl 1 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. .hl 2 Percent Signs Many addresses include imbedded percent signs; for example: .s .i8;TNIELAND%FALCON@AAMRL.AF.MIL .s 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 .s .i8;TNEILAND%FALCON^^^at^^^AAMRL.AF.MIL .s 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 .s .i8;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 .s .i8;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. .hl 2 Mixed Uucp/Domain Addresses Sometimes you will see an address of the form .s .i8;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 .s .i8;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 .s .i8;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: .s .i8;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! 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 How It Works .hl 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: .ls1,"o" .le;B.usAnnnn - a uuxqt command file to be sent to the remote system .le;C.them\_Annnn - commands to the local uucico program .le;D.usAnnnn - the actual mail file, with RFC822 headers .els0 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. .end note 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 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). .hl 1 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. .hl 1 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 .s .i8;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. .hl 1 Unix Compatibility Issues .hl 2 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. .hl 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. .appendix 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. .hl 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 them to the UUCP\_POSTMASTER. Here is a sample entry from uucp.log: .literal p:uucp << h:esther [04/20-16:48:49-0000051a] Startup ok (g) u:- .end literal 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. .hl 2 UUCP.LOG Entry Format Log entries follow a consistent format. Reading from left to right, the elements of entry are: .hl 3 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. .hl 3 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: .lm+8 .literal (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 .end literal .lm-8 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: .lm+8 .literal =< beginning X file processing << handing X file contents to UUXQT\_DCL .end literal .lm-8 .hl 3 Hostname The uucp hostname of the system at the other end of the serial link, preceded by "h:". .hl 3 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. .hl 3 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: .literal 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:- .end literal ("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. .hl 3 Event Description A very brief statement of the event, followed (usually) by additional information pertaining to the event. The latter is enclosed in parentheses. .hl 3 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 "-". .hl 2 Hints on Log File Interpretation .hl 3 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: .literal 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 .end literal 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. .hl 3 Throughput As shown in the following example, uucico will report the net throughput after each file transfer: .literal ...0000051a] File rcvd ok (370 bytes, 3 secs, 123 Bps) u:jeh@simpact.uucp .end literal 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. .hl 3 Benign "Errors" There is one "error message" that may appear after a call on a noisy line: .literal ...00000487] * Protocol stats (errs: 1 pks in/out: 5/13) u:jeh .end literal 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 "bursty" errors that predominate in serial communications. .hl 3 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. .hl 3 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): .ls1,"o" .le;Calling .le;Dial failed .le;Login failed .le;Sys entry too short .le;No ports avail .le;Bad .els0 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. .hl 3 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, .s .i8;$ search esther .s might find places in the log where "esther" appeared in file names, but .s .i8;$ search "h:esther" .s will just match where esther appears as a host name. .s .i8;$ search "0000051a]" .s will match all entries from the given process ID , and .s .i8;$ search "] * " .s will find all errors. Multiple search targets can of course be combined via the /match qualifier. For example, .s .i8;$ search "h:crash","] * "/match=and .s will find all error entries associated with host crash, and .s .i8;$ search "> h:crash","] *"/match=and .s will limit the search to outbound calls only. (It will also exclude entries from uuxqt, since all "calls" are "inbound" as far as uuxqt is concerned.) .hl 1 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 more useful 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: .lm+5 .s .no fill 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 .fill .s .lm0 (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. 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, and each time a terminal read times out while processing the expect statements for 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. .end note .hl 2 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. .hl 3 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 .literal 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:- .end literal 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.) 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. .hl 3 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^. There are good and bad things about this. The good part is that you can TYPE the batch job log file at any time, because it's available for shared read access. (You can't directly browse it with a text editor, or copy it for this purpose with COPY, but TYPE/OUTP=file will work.)~ The bad part is that uucico uses some of the C standard I/O library to write the debug log, and logs one-at-a-time character input and output (as for dial and login script processing) using printf() calls with no trailing newline. When writing to a separate file (as is done for inbound calls), or to a terminal, the C run-time library opens the file for Unix-style stream output, and you get output like .lm+8 .literal Sending slowly: A T Q 0 0x0D Doing expects for state wakemodem Received: A T Q 0 0x0D 0x0D 0x0A O K Matched: O K Changing to state dialnumber... .end literal .lm-8 which is what we want. But in the uucico daemon's batch log file, what you see is more like: .lm+8 .literal Sending slowly: A T Q 0 0x0D Doing expects for state wakemodem Received: A T Q 0 . . . .end literal .lm-8 Well, you get the idea. Uucico writes each of the logged characters (A, T, Q, 0) with a separate printf with no trailing newline, but the batch log file is created as a VFC file, each printf produces a new record in the file, and the VAX^C RTL does not generate the proper linespacing instructions. If you like you can cause the uucico batch job to send its debug output to a separate file; the comments in [.BIN]UUCICO\_CALLOUT.COM explain how. (The file name will be the same as that for inbound calls; see the preceding section.)~ Then the character I/O log output will readable, at least as much so as it ever is. But since it's a Unix-like stream file, we can't open it for shared access, so you'll have to wait until the process ends to look at it. Since the uucico daemon is supposed to be started when the system is booted and only go away when the system is shut down, this means you'll have to kill off the daemon and start up a new one if you want to look at the log. Life is full of tradeoffs. .hl 1 SYS$ERROR For inbound calls, SYS$ERROR is directed to a file called .s .i8;[.LOG]SYSERROR.pid .s 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!)~ .hl 1 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: .literal f: 0 c: 6 nf: 0 sq: 348 success outbound normal - [04/21-00:11:45-00000487] .end literal 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: .lm+8 .literal 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 .end literal .lm-8 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.) .hl 1 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]. .hl 1 Other Sources of Information .hl 2 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 name. .hl 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. .hl 2 The VMS Accounting File Don't forget that you can ask the Accounting utility to show you entries by PID: .s .i8;$ 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. .hl 2 Process Names Any process running uucico or uuxqt will set its name to .s .i8; .s 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. .literal 00000116 uucp >> scubed HIB 9 103982 0 00:26:28.84 85508 693 B 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 .end literal .hl 2 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. .hl 2 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. .hl 2 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. .hl 1 "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 .s .i8;Shere or, possibly, .s .i8;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. .hl 1 Restarting the Batch Jobs If any of uucp's batch jobs fails for any reason, enter the following DCL command to restart them: .s .i8;$ @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. .appendix Security Issues Unix uucp is notorious for being insecure by default. The paper "Uucp Implementation Description" by D\. A\. Nowitz says this: .lm+8 "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." .lm0 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]~ .footnote \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_ .s [1]^^This is why we are not providing a DCL "uucp" command with this release; we don't have a design that will^-- by default and in spite of common oversights on the part of the system manager^-- provide the necessary protection. (Suggestions for such a design would be quite welcome!)~ And we will {_never}_ provide a mechanism for arbitrary remote command execution: If you trust the other site that much, set up a DECnet link! .end footnote 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 a few problems. .hl 1 Decus Uucp Security Provisions .hl 2 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. 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. .hl 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. .hl 2 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.) .hl 2 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: .ls1,"o" .le;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. .le;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). .le;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. .le;The subprocess uses SETPRV to turn the needed privileges on just before executing rmail and rnews commands, and turns them off again immediately thereafter. .els0 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. .hl 2 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.)~ .hl 2 "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. 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"). .hl 1 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. .hl 2 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 for this inquiry. .end note 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 Trailblazer modems), but if the prospect bothers you, you can always set an appropriate disk quota for the uucp login. .hl 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. .hl 2 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.) .hl 1 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. 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. .hl 1 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. .hl 1 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 Future Directions With the version distributed on the Fall '89 VAX Systems SIG tape, we will cease attempting to support VMS Version 4.x. This extends not only to the provision of image files but also to the use of new-with-Version-5 RTL routines, DCL features, and so on. We are investigating a redesign of UUCP\_MAILSHR such that we will not have to enable BYPASS, etc., before delivering inbound mail. Ned Freed has expressed interest in enabling PMDF to forward mail to and from DECUS uucp. We will certainly give him whatever support we can in this. We will support a "DECnet channel", wherein the "portname" item in a systems entry would provide a DECnet remote task specification. This will allow store-|and-|forward mail transfer through existing DECnet links. .appendix 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: .ls1,"o" .le;We may already have done it, or .le;We may have thought about it and made provisions for doing it in a different way, or .le;We may already have done something else that precludes your implementation from working, or .le;We may, for some other reason, have {_very}_ strong requirements on how it needs to be done. .els0 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. .ls1,"o" .le;Local variables and function names should be in lowercase; globals (externals) should have their first character capitalized. Defined symbols should be in all caps. .le;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. .le;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. .le;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. .els0 .appendix Acknowledgements .hl 1 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. .hl 1 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.)~ The original versions of gnuucp, uuxqt, and Bison are Copyright by the Free Software Foundation, and are made available under the terms of the GNU software license. Basically this license says that you can do anything you want with the code, as long as you don't place any restrictions on what anybody you give it to can do with it, and that you must distribute all of it (including sources) if you redistribute any of it. Recipients of this software are asked to comply with these terms. (The full text of the GNU software license may be found somewhere in [.ORIG\_CODE...].)~ Our changes and additions to these programs are in the public domain.