sources-request@mirror.UUCP (10/31/86)
Submitted by: seismo!rick (Rick Adams) Mod.sources: Volume 7, Issue 47 Archive-name: 2.11news/Part07 # To extract, sh this file # # news 2.11 documentation File 5 of 6 # if test ! -d doc then mkdir doc fi if test ! -s doc/install.mn then echo "First half of doc/install.mn is missing. shar aborted" exit 1 fi echo "x - doc/install.mn (second half)" 1>&2 sed 's/.//' >>doc/install.mn <<'*-*-END-of-install.mn-*-*' -.hn 1 -Format of the -.bi sys -file -.pg -To set up a link to another site, -edit the -.i sys -file in -.b LIBDIR . -This file is similar to the -.i L.sys -file of UUCP. -Each line contains four fields, -separated by colons: -.Lp (1) -The system name of a site to which you forward news. -Normally all systems you have links to will be -included. -You should also have a line for your own system. -If this field is -.cn ME, -it will be used as if it were your local system name. -If the system name is followed by a \*(lq/\*(rq, the article will not be -forwarded to this system if it has already passed through any of the -(comma separated) list of sites immediately following the \*(lq/\*(rq. -For example, if the sysline was: -.sd c -yoursite/sitea,siteb,sitec:world,comp,sci,news,rec,misc,na,usa,to.yoursite:: -.ed -the incoming article would only be forwarded to -.i yoursite -if it had not already been to any of -.i sitea , -.i siteb , -or -.i sitec . -This is normally used to reduce the number of duplicate articles received -at a site that has multiple main newsfeeds. -.lp (2) -The newsgroups to be forwarded to that site. -This is a pattern of the same kind as a subscription list. -Generally, -you will list classes of newsgroups, -that is, -using -.ng all -for everything. -A typical forwarding list for a new site would be -.sd c -world,comp,sci,news,rec,misc,soc,talk,na,usa,to.\f2sysname\fP -.ed -where -.i sysname -is the name of the remote system. -(Of course, if you are not in the USA or North America, -you would remove those distributions -and replace them with the ones appropriate for you.) -In particular, -you don't want to forward -.ng all -since local newsgroups -(those without dots) -should not be sent. -For the line describing your own system, -this field describes the newsgroups your site will accept from remote sites. -Thus, -if another site insists on sending you a newsgroup you don't want, -for example -.ng rec.humor , -include -.ng !rec.humor -here. -.lp (3) -This field contains flags describing the connection. -.Qp A -indicates that the other site is running an A version of netnews. -.Qp B -indicates a B version. -Leaving it empty defaults to -.b B . -If you are reading this document, -you have a B version. -Some existing sites run A versions. -If you aren't sure, -ask your contact at the other site, -with whom you should be talking to set this up anyway. -.Qp F -indicates that the fourth field is the name of a file. -The full path name of a file containing the article in -.b SPOOL -will be appended to this file. If the fourth field is blank, the filename -.b BATCHDIR \f2/sysname\fP, -(where -.i sysname -is specified in the first field) will be used. -.Qp L -prevents transmission unless the article was created on this site. -If a number follows the -.b L -.i e\f1.\fPg ., ( -.b L3 ), -sites less than that number of hops away will be considered local. -(It is recommended that you feed an -.b L -link to a backbone site, -to ensure that your submissions will be more likely -to get to the entire network, -even in the event of a local problem. -Please make sure that a mail link exists too, -so you can get replies.) -.Qp H -can be used to interpolate the history file into the command. -.Qp S -says to execute the transmission command directly -instead of forking a shell. -.Qp U -arranges that the parameter to the optional \*(lq%s\*(rq -in the command field to be filled in with a permanent file name from -.b SPOOL -instead of a temporary customized file name. -.Qp M -says to use multi-casting. Multi-casting is described in an appendix. -.Qp I -automatically defines the -.b F -flag. However, it puts the article's -.i Message-Id -into the file instead of the filename containing the article. This is -used with the -.i ihave/sendme -control messages. -.Qp m -(lower case -.b m -not upper case -.b M ) -modifies the newsgroup pattern match to only return true if it -matches the pattern in the second field AND the group is moderated. -For example, if your -.i sys -file looked like: -.sd c -avax:world,comp,sci:mF:/usr/spool/batch/avax.sendimmediately -avax:world,comp,sci,rec,talk,misc,soc,to.avax:F -.ed -.ei -any moderated articles in the newsgroups -.ng comp -or -.ng sci -would be placed in the file -.i avax.sendimmediately -in the -.b SPOOL -directory. -All other news for that machine would be placed in the file -.i avax . -You could then transmit the articles in -.i avax.sendimmediately -more often than the rest of the news. -.Qp u -works like -.b m -except that it only matches un-moderated newsgroups. -.Qp N -indicates that news should be sent using the ihave/sendme protocol. -It should not really be used anymore as -.b I -is much more efficient. -.lp (4) -This field is the command to be run to send news to the remote site. -The article will be on the standard input. -Leaving this field blank means an ordinary UUCP link is being used, -that is, -the command defaults to -.sd c -uux \- \-r \-z sysname!rnews -.ed -The -.op \- -option tells -.i uux -to expect input from the standard input. -The -.op \-z -option is nonstandard \- you should add it -(see the -.i minus.z -files in the uucp source directory). -It shuts off the annoying message you would otherwise get mailed to you -telling you that your article was broadcast successfully. -To avoid using the -.op \-z -option, -change the source or put the -.i uux -command in the fourth field. -The -.op \-r -option tells -.i uux -not to call the other system once the job is queued. -This turns out to ease the load on the system, -at the expense of making news be transmitted a bit slower. -The news will be sent when the next call is made; -usually this means the next time mail is sent to or from your system. -If this turns out to be unreasonably long, -put a line in -.i crontab -to run -.sd c -/usr/lib/uucp/uucico \-r1 \-s\f1sysname\fP -.ed -every hour or so. -.pg -Here is a sample -.i sys -file for a site -.cn myvax -with connections to -.cn yourvax -where -.cn myvax -also passes news on to -.cn downstream . -We assume that -.cn myvax -and -.cn downstream -exchange a local newsgroup class -.ng lng.all -as well as the network wide newsgroups. -News to -.cn downstream -is batched. -We also assume that -.cn myvax -and -.cn yourvax -are in the USA, -while -.cn downstream -is in Canada. -.sd -myvax:world,comp,sci,rec,news,misc,soc,talk,na,usa,lng,to -yourvax:world,comp,sci,rec,news,misc,soc,talk,na,usa,to.yourvax -downstream:world,comp,sci,rec,news,misc,soc,talk,na,lng,to.downstream:F -.ed -.hn -Posting Methods -.pg -The basic method is -.i postnews . -This program will prompt you for the title, -newsgroups, -and distribution, -then place you in the editor. -(The system default -.b EDITOR -is used unless the environment variable -.b EDITOR -is set, -overriding the system default.) -The text should be typed after the blank line. -The title and newsgroups are available for editing at the top of the buffer. -Other header lines can be added, -such as an expiration date or a distribution. -When you write out the file and exit from the editor, -you will be prompted for what to do next. Your choices are: -.b w rite -the message to a file, -.b s end -the message, -.b l ist -the message or -.b e dit -it again. -.pg -Another method is to use mail. -This can only be done on systems that allow mail to a given name -to be fed into an arbitrary program as input. -This is easily done with the Berkeley -.i delivermail -or -.i sendmail -program, -and not with any other mailer the author is familiar with. -(It may be possible to painfully set this up with MMDF, -provided the newsgroup name is no more than 8 characters long.) -To use mail, -set up an alias such as the following: -.sd c -sci.physics: "|\fBLIBDIR\fP/recnews sci.physics" -.ed -Whenever a user sends mail to -.ng sci.physics , -this starts up the given shell command which calls -.ng recnews -with one argument, -the name of the newsgroup. -You need to create one alias for each newsgroup, -and to keep the list up to date as new newsgroups are created. -.i Recnews (8) -will in turn invoke -.i inews . -.pg -Note that there are problems with -.i recnews . -There is no way to use it to post to multiple newsgroups -without creating separate articles -(something frowned upon because it forces people -to read the same thing more than once). -Also, -there is no way to make the recording feature -(to remind people to not accidently divulge proprietary information) -work when recnews is used. -.hn -Various considerations -.hn 2 -Spooling -.pg -If -.i expire -is already running and -.i inews -or -.i rnews -is invoked, the incoming article will be saved in -.b SPOOLDIR /\f2.rnews\fP -for later processing by -.i "rnews \-U" . -This is to prevent the incoming article from getting -\*(lqlost\*(rq and not being in the history file. -.i Expire -automatically runs -.i "rnews \-U" -when it has finished. -If you have defined -.b SPOOLNEWS , -you should also invoke -.i "rnews \-U" -from crontab on a regular basis. -.pg -If you are not using some type of \*(lqsystem\*(rq locking (\f2e.g. flock()\fP or -\f2lockf()\fP) you must make sure that the various lock files are -removed when the system is rebooted after a crash. You can put a line -in -.i /etc/rc -to remove these lock files. The most important one is -.b LIBDIR \f2/active.lock\fP. -.hn 2 -Setuid bits -.pg -The current intended state of affairs is that -.i inews -runs setuid to -.b NEWSUSR . -The -.i readnews -and -.i vnews -programs do not need to be setuid. -This makes it possible to write your own interface to read news instead of using -.i readnews . -(As distributed, -.i inews -is also setgid. -I know of no good reason for this.) -.hn 2 -Modes of Spool Directories -.pg -All the files should be writable by -.b NEWSUSR . -However, -due to a glitch, -you will probably have to make the -.b SPOOLDIR -and its subdirectories mode 777. -It could be 755 except for one problem. -When a new newsgroup comes in, -.i inews -will attempt to -.i mkdir (1) -a new subdirectory of -.b SPOOLDIR -for the newsgroup. -Since both -.i inews -and -.i mkdir -are setuid, -.i mkdir -will use the uid of the person who ran -.i inews -instead of -.b NEWSUSR -when checking for permissions. -If the directory mode isn't 777 the check will fail. -4.[23] BSD sites do not have this problem as -.i mkdir () -is a system call and will create the directory with the \*(lqcorrect\*(rq -ownership. -Here are several alternatives if you don't want a 777 directory around: -.hn 3 -Fix Real Uid -.pg -If -.i inews -is always run by -.i cron -or as -.i root , -the real uid can be arranged to be -.i root -or -.b NEWSUSR . -This is a poor solution -since it makes the local creation of new newsgroups -require super user permissions, -and is a potential security hole. -If this approach is taken, -care must be taken to ensure that the owner of the created directory is -.b NEWSUSR . -.hn 3 -Change the Kernel -.pg -.i Inews -will do: -.b setuid(geteuid()) -(see -.i setuid (2) -and -.i geteuid (2)) -before it forks the -.i mkdir . -If your system permits this call, -there will be no problem. -In particular, -Berkeley 4.0 -.ux -and later systems allow this. -An alternative change to the kernel is to automatically stack uids: -when a setuid program is run, -set the new real uid to the old effective uid. -.hn 3 -Groups -.pg -You could have -.i inews -be setgid to -.b NEWSGRP -and all files writable by the group. -This approach has been tested and the problem turns out to be that the -.i mkdir -command uses the -.i access (2) -system call to check permissions. -Since -.i access -uses the real gid, -you run into the same problem. -.hn 3 -Another -.bi Mkdir -.pg -You could create a version of -.i mkdir -that does less checking and put it in a directory that can only be accessed by -.b NEWSUSR -(mode 700, -owned by -.b NEWSUSR ). -Have -.i inews -fork this -.i mkdir . -.hn 2 -Expiration dates -.pg -To get articles to expire automatically, put a line in -.i crontab -to run -.sd c -\fBLIBDIR\fP/expire -.ed -every night. -This command deletes all expired news. -The -.op \-a -.i newsgroups -option causes all expired news to be archived under -.i /usr/spool/oldnews -depending on which newsgroups are selected. -(See -.i expire (8) -for details.) -.pg -Sometimes news is not expired when it should be. -Be sure to check that -.i expire -has permissions to unlink files, -and that it is properly setuid to -.b NEWSUSR . -You can manually invoke -.i expire -with the -.op \-v -(verbose) option to find out what it's doing. -Adding levels of verbosity -.i e\f1.\fPg ., ( -.op \-v6 ) -will get more and more output. -.hn 2 -Version to Version -.pg -Version B will understand incoming news in either version A or B format, -automatically (presuming -.b OLD -is defined in defs.h). -Version B -will generate either format, -depending on the flag in the third field of the -.i sys -line. -Version A will not understand version B format. -Thus, -it is possible for two version B -sites to communicate using version A -format. -This will work but is not a good idea, -since the translation from B to A loses information -(such as the expiration date) -which will not be there when translated back to version B. -.pg -News from versions A and 2.9 B -do not conform to the USENET interchange standard. -2.10 B (and later) supports the standard and will communicate with either A or 2.9 B news. -A news is written (losing other header information) if -A is in the flags for the system. -If -.b OLD -is defined, -2.10 will write out headers with both standard -.hf Date "" ( -.hf Message-ID ) -and 2.9 -.hf Posted "" ( -.hf Article-I.D. ) -lines so that either B system will properly handle the article. -Incoming news is recognized by the first letter -.qp A "" ( -for A news), -or the lack of an -.cf @ -in the -.hf From -line (2.9). -Missing fields are constructed as well as possible -from the available information. -.hn 2 -Using the news reading program rn -.pg -You must have installed all posted patches to -.i rn -up to and including #30. -Otherwise, -.i rn -will not work properly with news 2.11. -.hn 2 -Distributions -.pg -News 2.11 is much more particular about handling distributions than -previous versions. In particular, make sure that you have the distribution -.i world -in every line of your -.i sys -file unless you are specifically limiting the distribution and are -sure you know what you are doing. -.hn -Control Messages -.pg -Some news systems will send you articles that are not for human consumption. -They are messages to your news system called -.i "control messages" . -Such messages contain the -.hf Control -header. -Older systems use newsgroups matching -.ng all.all.ctl , -and this will still work, -although the -.hf Control -header is preferred. -Since the newsgroup name is used for distribution only, -and is not checked to ensure it's in the active file, -such newsgroup names can still be used. -This makes it possible to post network wide control messages with -.ng world.msg.ctl -(or restricted broadcast such as -.ng btl.msg.ctl ) -or messages for a particular system: -.ng to.ucbvax.ctl . -Messages are canceled, -however, -with a -.hf Control -line in a message to the same newsgroup(s) -as the original message. -.pg -A control message contains a command and zero or more arguments -(much like a -.ux -program). -The subject of the article contains the command and arguments. -The body of the article is usually ignored, -although some messages can use it for additional text information. -.hn 2 -ihave/sendme -.pg -Two control messages are -.b ihave -and -.b sendme . -These messages allow two participating sites to set up a link -so that one site will tell the other site it has a given article -and wait for a request before it actually sends it. -The normal case is to send an entire article to a system, -which consults the history file to see if the article has already been seen, -and then throws it away if it has been seen before. -.pg -Use of these control messages can cut down on this wasted transmission, -but if you have a polled UUCP connection, -they can slow down receipt of news due to polling delays. -It is up to each connected pair of sites whether they want to use this protocol. -The choice is controlled by the -.b I -flag in the -.i sys -file. -In the case of a leaf node -(one with only one neighbor) -there is no advantage to this protocol. -Even if both sites are able to initiate a connection -(have dialers or the link is hard wired) -the -.op \-r -option on the -.i uux -can cause 2 hour or more delays in propagating news. -If transmission time and phone bills dominate your costs, -and you are sending news to several sites, -and large article bodies dominate the costs -(rather than the headers and the time spent by UUCP negotiating transmission) -it is probably worthwhile to use -.pa ihave/sendme . -If your costs are dominated by CPU load from UUCP, -or if you send news to a site that cannot get it from anywhere else, -you probably do not want to use this protocol. -The decision can be made independently for each site in your -.i sys -file. -.pg -To use the ihave/sendme protocol, you should have the -.b I -flag defined in the sys file for the remote site. For example: -.sd c -elsie:world,na,usa,comp,sci,news,rec,soc,misc,talk,to.elsie:IF -.ed -.pg -Note that the fourth field must be blank. -.pg -Normally, a message arrives at this site, is found to be ok (i.e. it hasn't -already been received), and is considered for retransmission to other -sites. If the system you are sending to has the -.B I -flag defined, the Message-ID -is saved in the file specified in the sys entry. -.pg -After a period of time, -.sd c -sendbatch \-i elsie -.ed -is run by -.i cron (8). -It takes this file, makes it into an -.b ihave -control message, and sends it to the other site. -When the message is received on the other site, the Message-IDs -are looked up, and if any of the messages have not been received, they are put -into a -.b sendme -control message. When the -.b ihave -message has been fully processed, -the -.b sendme -message is sent to the site that sent the -.b ihave -message. -.pg -When the orignal site receives the -.b sendme -message, it sends the requested articles in the format designated by the -.i sys -file (the -.b I -flag is ignored in this case). In this example, it would write into the -file -.b /usr/spool/batch/ \f2elsie\fP -for later processing by -.i sendbatch . -.hn 2 -newgroup -.pg -This message has one or two arguments, -the name of a newsgroup to be created and the second optional argument -.i moderated . -This allows special action to be taken locally when a new newsgroup is created. -It is generated by the -.op \-C -option to -.i inews . -By default, -the newsgroup is added to the active file, -and mail is sent to the local contact advising that this has happened. -The directory will be created when a message for that newsgroup arrives. -If -.b NONEWGROUPS -is defined, the newsgroup will not be created and -.b NOTIFY -will be sent mail explaining how to do it manually. -See the routine \*(lqc_newgroup\*(rq in -.i control.c -if you want something different to happen. -(Note that, -although the body of the message contains a brief description -of the purpose of the group, -this body is usually thrown away by existing software.) -If the second argument is the keyword -.i moderated , -the newsgroup is created moderated, else it is unmoderated. -.hn 2 -rmgroup -.pg -This message has one argument, -the name of a newsgroup to be removed. -It is used for network-wide cancellation of a newsgroup. -If -.b MANUALLY -is not defined, -it will remove the articles, -directory, -and active file line for the group. -There is a shell script -.i rmgroup -that does essentially the same thing as this message, -but the shell script only removes the group locally. -We recommend that you leave -.b MANUALLY -defined, -and when you receive mail advising you of the demise of the newsgroup, -you run -.i rmgroup -by hand. -This will prevent accidental or malicious removal of a good newsgroup. -.hn 2 -cancel -.pg -This message cancels a given article. -It takes one argument, -the message id of the article to cancel. -It should be broadcast to the same newsgroup as the original article. -If the article to be canceled is not present, the control message -will not be propagated to downstream sites. -.hn 2 -sendsys -.pg -The -.i sys -file is mailed to the originator of the message. -There are no arguments. -This is used for making maps. -Since your -.i sys -file is public information, -you should not remove or change this control message. -.hn 2 -senduuname -.pg -The -.i uuname -program is run and the output is mailed to the originator of the message. -There are no arguments. -This was used for making UUCP maps. -It is of questionable use any more. -If you do not run UUCP or have sites in your -.i L.sys -which are a secret, -you may wish to edit this. -Note that only the output of -.i uuname -is mailed, -not the contents of -.i L.sys -(which news does not have access to anyway). -If you do make a change, -you should arrange that some mail still is sent out -to the originator of the message, so the originator will know your site -received it. See the code in routine \*(lqc_senduuname\*(rq in -.i control.c . -.hn 2 -version -.pg -The local version name/number of the netnews software -is mailed back to the originator of the control message. -.hn 2 -checkgroups -.pg -This control message is an attempt at semi-automatic maintenance -of the list of active news groups. -This control messages takes the body of the article and pipes it into -.bi LIBDIR \f2/checkgroups\fP. -As mentioned previously, -.bi LIBDIR \f2/checkgroups\fP -will update the newsgroups file, -add any missing newsgroups, and mail a message to -.b NOTIFY -about any old newsgroups that should be removed. -It is expected that the person who maintains the list of active newsgroups -will broadcast this control message on a regular basis. -.hn 2 -Other Messages -.pg -Any unrecognized message will cause an error message to be mailed -to the local news administrator. -Additional messages may be defined as time goes on, -such as messages to automatically update directories or maps. -You should be willing to go into the code -.i control.c ) ( -and add messages as they become standardized. -.hn -Maintenance -.pg -There are some things you should do periodically -to keep your news system running smoothly. -We hope to eventually automate all or most of this, -but right now some of it must be done by hand. -.pg -The -.i history -and -.i log -files in your -.b LIBDIR -directory will grow. -You should make sure that they are cleaned up periodically. -The -.bi LIBDIR \f2/expire\fP -program will remove lines from history corresponding to deleted articles, -but it is a good idea to check the file every few weeks -to make sure it is not going wild. -Be sure not to completely lose your history file when you clean it up, -in case another neighbor tries to send you an article you recently got. -(If you only get news from one site it is safe to clean it out completely.) -.pg -The log file is not automatically cleaned out by any netnews software, -and will grow quickly. -The -.i misc/trimlib -script can be installed in -.bi LIBDIR \f2/trimlib\fP, -and invoked regularly by -.i cron (8). -.pg -You should also clean out old newsgroups that are no longer active. -To remove a newsgroup -.ng misc.foo , -you should run the shell script -.i rmgroup -with -.b misc.foo -as the argument. -That is, -.sd c -\fBLIBDIR\fP/rmgroup misc.foo -.ed -.pg -Note that clearing up UUCP constipation is another thing you'll have to do -if you have flaky hardware or phone lines. -If you have more than one connection, -chances are that UUCP will get clogged up when one of your neighbors goes down -for more than a few hours. -Various spooling schemes are being worked on -to help make the news/uucp system more robust, -but one thing you can and should do, -if you find your -.i /usr/spool/uucp -directory getting too big, -is to install a subdirectory fix to UUCP. -A quick and dirty version of this is available from Duke, -which traps the file-oriented system calls -at the assembly language level and maps, -for example, -D.fooA1234 into D.foo/D.fooA1234. -Since the C. and -.i local "" D. -directories still get big, -in practice this can still create some big directories, -but the directories tend to be a factor of 5 smaller, -resulting in a factor of 25 improvement to speed -(since a directory traversal for all files is quadratic on -.ux ). -Right now, unless you have the uucp distributed with 4.3 BSD or the so called -.i HoneyDanBer -uucp, -UUCP is the weak link in netnews distribution, -and you should certainly keep an eye on it. -.hn -Creating New Newsgroups -.pg -As system news administrator, -you are able to create newsgroups. -To create a newsgroup, -first make sure this is the right thing to do. -Normally a suggestion is first posted to -.ng news.groups\f1,\fPwhatever.relatedgroup -for a world wide newsgroup -.b whatever.relatedgroup "" ( -should be the group which you are proposing to sub-divide. -For instance, -to propose creating -.ng rec.arts.tv.soaps , -post the original article to -.ng rec.arts.tv\f1,\fPnews.groups .) -Followups are made to -.ng news.groups -.i only . -(You can force this by putting the line: -.sd c -Followup-To: news.groups -.ed -in the headers of your original posting.) -If it is established that there is general interest in such a group, -and a name is agreed on, -then someone creates it by typing the command -.sd c -inews \-d local \-C \fInewsgroup\fP -.ed -This will create the active entry locally. The directory will be -created automatically when the first article for that newsgroup is -received. -It will also prompt you for a paragraph describing the group and start up an -.i inews -to post a newgroup control message announcing the group. -.pg -You must be the super user to use the -.op \-C -option to -.i inews . -(That is, your uid must match -.b ROOTID . -It is recommended that you change -.b ROOTID -to your own uid so you don't have to -.i su -to create newsgroups.) -If you change the distribution to be something other than local, the -newgroups message will be sent to the specified distribution. -.hn -Conversion from A to B -.pg -If you are currently running version A on your system, -note that B is incompatible with A. -The files are stored in a different format -(headers have mail like field names now). -The directory organization is different -(each newsgroup has a subdirectory of its own, -and the file names are numbers rather than -.i site\f1.\fPid -pairs). -There are no -.i bitmap , -.i uindex , -or -.i nindex -files to be trashed -(which articles have been read is stored in each users -.i .newsrc -file). -The user interface is slightly different -.i netnews (1) (news/ -is now called -.i readnews , -news is posted using -.i inews , -subscription is done by editing -.i .newsrc , -the sense of the -.op \-c -option is reversed, -news is presented in newsgroup order, -the -.op \-a -and -.op \-t -options now probably need -.op \-x -as well, -and there are many minor changes). -.pg -We decided not to provide a program to convert from version A to version B. -Rather, -the following strategy was adopted for conversion: -.lp (1) -Install the new news in a different spool directory from the old one. -For example, -you can use -.i /usr/spool/newnews . -You can change to the standard name later if you want. -Get it to work for local messages. -.lp (2) -Post an article to newsgroup -.b general -with the old news announcing the change. -Make available documentation such as the accompanying paper -.i "How to Read the Network News" -to the users. -This article will be the last one in the old news. -.lp (3) -.i Chmod -the old news directory to 555 to prevent any more news from being posted. -(Actually, -this will prevent the bitfile from being updated, -so it may not be a good idea.) -.lp (4) -Replace the old -.i rnews -program with the new -.i rnews -program. -.lp (5) -Test it by having your neighbor send you a message. -.lp (6) -Wait a reasonable period for everyone to have read the final article -with the old news. -Perhaps a few weeks is right. -.lp (7) -Uninstall the old news. -.pg -Users will have to invoke -.i readnews -instead of -.i netnews -to read news. -Depending on your old method of posting, -this could be changed too. -(If you were using mail, -it does not need to be changed.) -They will also have to fix their subscriptions. -In general, -they can type -.sd c -netnews \-s -.ed -to see what they subscribe to on the old system, -and then create a file in their home directory called -.i .newsrc -containing -.sd c -options \-n \f2their subscription\fP -.ed -The format of the subscription pattern matching is the same as in A -except that -.ng ALL -is replaced by -.ng all -(change to lower case). -Something along the lines of this could be used to automate this: -.sd c -(echo \-n "options \-s" ; netnews \-s | sed s/ALL/all/) > .newsrc -.ed -.hn -Conversion from 2.9 to 2.11 -.pg -Conversion from 2.9 to 2.11 is not nearly as involved as an A to B conversion. -The user interface does not change much, -and the user -.i .newsrc -files are not affected. -However, -it is recommended that you do the conversion during a time -when no news is received, -so that incoming news will not get lost. -One way to ensure this is to make -.i /usr/bin/rnews -be a shell script which saves the article in -.bi $$ "" /usr/spool/innews/ -.bi $$ "" ( -is the process id of the particular shell and will be unique for each article). -.pg -The first step to conversion is to customize the sources. -In the past, -you had to take a fresh distribution and edit the -.i defs.h -file and -.i Makefile -to suit local preferences. -If you had many local changes, -or didn't record the local changes, -upgrading could be annoying. -2.11 provides a mechanism to automate these changes. -Create a shell script in the src directory called -.i localize.sh . -(You can use -.i localize.sample -as a template.) -This shell script should copy -.i defs.dist -to -.i defs.h , -and copy -.i Makefile.dst -to -.i Makefile . -It should -.i chmod -any files that need to be changed -(often -.i Makefile -and -.i defs.h ) -to a writable mode. -Then it should invoke -.i ed (1) -on the files, -making any necessary local changes. -.pg -The next step is to compile the software, -with -.i make (1). -It may be necessary to update the -.i localize.sh -file until you are satisfied with the compilation. -Note that after any change to the -.i Makefile -in -.i localize.sh , -you should run -.i localize.sh -by hand. -Otherwise, -although make will run it for you, -it will then continue to do the make with the old -.i Makefile . -.pg -When the software is compiled, -you should run the -.i cvt.active.sh -shell script, -with the -.i lib -and -.i spool -directories as parameters. -This will create a new active file in -.bi LIBDIR \f2/active\fP. -Then run -.i cvt.links.sh -with the -.i lib -and -.i spool -directories as parameters. -Then run -.i cvt.names.sh -with the -.i lib -and -.i spool -directories as parameters. -Old news will be linked into the new hierarchy -while leaving links in the old hierarchy. -If you were using the default library and spool directories, -you would do the following: -.sd -sh cvt.active.sh \fBLIBDIR\fP /usr/spool/news -sh cvt.links.sh \fBLIBDIR\fP /usr/spool/news -sh cvt.names.sh \fBLIBDIR\fP /usr/spool/news -.ed -.pg -The next step is to back up the old binaries: -.sd -mv \fBBINDIR\fP/rnews \fBBINDIR\fP/ornews -\&... -.ed -and to install 2.11 with -.sd c -make install -.ed -Once it is installed, -any incoming news will be placed into the new hierarchy but not the old one. -The critical time window is between running the three shell files and -installing the new software \- -any incoming news between these two points will appear -in only the old hierarchy and be lost to the new software. -If any significant time elapses here, -you should divert -.i rnews -into a separate spool directory as described above. -.pg -It is crucial that you run -.i expire -before any new news arrives. -.i Expire -will update several key files automatically. -.pg -Finally, -test things by posting articles to -.bi neighbor "" \f3to.\fP -newsgroups and watching some incoming news, -and announce the change to your users. -.pg -When you are satisfied that the conversion was successful, -run the shell file -.i cvt.clean.sh -which will remove the old 2.9 news hierarchy. -.hn -Converting from 2.10.x to 2.11 -.pg -Converting from version 2.10 or later to 2.11 requires no special -intervention. All files are updated automatically when you do -\*(lqmake update\*(rq. -.bp -.hu -Appendix A: Setting up a Compressed, Batched Newsfeed -.pg -First, -.b BATCH -must have been -.i #define 'd -when you built the news system. -To check, -look in the file -.i defs.h -in the news source directory. -.b BATCH -should be defined as a program name (by default, -.i unbatch ). -If it's undefined or commented out, -define it, -re-make the news system, -and install the new software. -.pg -You'll also need a working -.i compress -program. -Use the one shipped with this news distribution, -which is based on version 4.0. -Your news neighbors should be running a compatible version of compress. -Versions 3.0 and 4.0 are compatible with each other, -but both are incompatible with versions 2.0 and earlier. -.pg -Update your -.i sys -file. -First, add the -.b F -flag to the other news system's line. For instance, -if your compressed-and-batched news feed is named -.cn frobozz , -and its -.i sys -file entry looks like: -.si -.sd -frobozz:world,comp,sci,rec,misc,soc,talk,news,na,usa,ca,to.frobozz -.ed -.ei -then add the -.b F -flag as the third (colon-separated) field: -.si -.sd -frobozz:world,comp,sci,rec,misc,soc,talk,news,na,usa,ca,to.frobozz:F -.ed -.ei -Now the pathnames of articles to be sent will be stashed in a file. -This file can be specified in the fourth field of the -.i sys -entry. -Normally, you can just use the default of -.bi BATCHDIR \f2/system\fP, -(where -.bi BATCHDIR -is usually -.i /usr/spool/batch -and -.i system -is the name of the remote system, -in this example -.cn frobozz ). -A name of that form is necessary: -the -.i sendbatch -script, -which sends the batched news, -looks for a file name of this form -to decide if there's news for the remote system. -.pg -Your completed -.i sys -file line should look something like: -.si -.sd -frobozz:world,comp,sci,rec,misc,soc,talk,news,na,usa,to.frobozz:F -.ed -.ei -.pg -In your -.i crontab -file, find or create at least two news lines: -one that runs nightly, -and one that runs every hour or so. -The nightly-run script should run -.i expire , -trim log files, -and perhaps compile weekly statistics -that you post to a local-area newsgroup one day a week. -The hourly-run script should complete the transmitting task -with a line like: -.sd c -sendbatch -c frobozz -.ed -Make sure the script knows how to get to the directory in which -.i sendbatch -lives. -You can either mention the directory in the script's -.b PATH -setting -line, -or replace -.i sendbatch -with its full pathname. -.i Sendbatch -reads the files mentioned in -.i /usr/spool/batch/frobozz , -batches them, -optionally compresses them, -sends them to the remote system, -and arranges for remote processing. -.pg -This remote processing can be directed by another file in -.b BATCHDIR . -Make an executable file with a name of the form -.bi BATCHDIR \f2/system\fP.cmd -(for this example, -.i /usr/spool/batch/frobozz.cmd ). -Put a line in it specifying the command that the remote system -should execute to unpack the news batches that your system will send. -An example -.i frobozz.cmd -would be: -.sd c -uux - -r -z -n -gd frobozz!rnews -.ed -.pg -Now your system will transmit compressed batches. -The receiving side of the business is handled largely by a program called -.i rnews , -which will call other programs in -.b LIBDIR -to do additional processing on the incoming batches. -.pg -Make sure there is an executable file called -.i rnews -in the -.b BINDIR -directory -(check the -.i Makefile -for its actual location). -It must be reachable by UUCP -or by whatever transport you'll use to transfer the netnews. -If you defined -.b BINDIR -as -.i /usr/bin , -you should have no problems because -.i uuxqt -can already get there. -If you defined it as a different directory, -you may have to teach -.i uuxqt -to look in that directory; -accomplishing this varies from system to system. -On 4.[23] BSD, add the directory to the -.b PATH= -line of your UUCP -.i L.cmds -file. -On System V, -on the -.i rnews -line of your -.i L.cmds -file, -add a comma followed by -the remote system's name on that line. -If yours is in -.i /usr/bin/news/rnews , -your -.i L.cmds -file will look like: -.si -.sd -[For 4.[23]BSD] -PATH=/bin:/usr/bin:/usr/bin/news -rnews -.ed -.sd -[For System V] -/usr/bin/news/rnews,frobozz -.ed -.ei -Other systems have a similar file in the -.i /usr/lib/uucp -directory by which you can specify added programs -and paths different from the defaults. -HP-UX, -for example, -has a -.i /usr/lib/uucp/COMMANDS -file which expands -.i uuxqt 's -horizons. -.i HoneyDanBer -uucp -.i a.k.a " AT&T Basic Networking Utilities)" ( -has a -.i Permissions -file that controls what is executed. -In more restrictive cases, -paths are compiled into -.i uuxqt . -If you can't modify any UUCP files, -just put -.i rnews -in -.i /usr/bin. -.pg -Tell the person at the other end of your newsfeed to use -.i "sendbatch \-c" -to send you news. -Once that's in place, -watch your UUCP -.i LOGFILE -and your news -.i log -and -.i errlog -files to ensure that news is being correctly received and unpacked -on your system. -.pg -Older compressed batching systems will try to exec -.i cunbatch -instead of -.i rnews . -If you are still communicating with these, leave -.i cunbatch -in -.b BINDIR -until they have upgraded their software. -.bp -.hu -Appendix B: MULTICAST -.pg -If this is defined (in -.i defs.h ) -then two new flag characters -become defined in the -.i sys -file. -The first, -and most important, -of these is the -.b M -flag. -.pg -If the -.b M -flag is set on some line in the -.i sys -file, -then the fourth field (transfer command) is redefined to become a -.i multicast -name. -That is simply another system name, -expected to be found in the first field of some line in the -.i sys -file (textually following the line containing the -.b M -flag). -.pg -When a news item is being retransmitted, -if it should (according to the subscription list) be sent to a system -that has the -.b M -flag set, -then instead of a command being run immediately to transmit the news, -the news system remembers the system name, -along with the multicast name (fourth field). -.pg -Eventually the multicast system name is found in the first field of a sys -file line. If its subscription list allows transmission of this news item, -then its command will be executed. -This command may have up to two \*(lq%s\*(rq substitutions in it. -The second of those is replaced by the name of a file -containing the news item (used with the -.b U -flag). -The first is subjected to rather special treatment. -The whole \*(lqword\*(rq (delimited by white space) -containing that \*(lq%s\*(rq is duplicated as many times -as there were systems with the -.b M -flag set that referenced this multicast name -(which might be 0 times, -causing that \*(lqword\*(rq to be omitted). -In each of these duplicates, -the \*(lq%s\*(rq is replaced by the name of a system. -Note the multicast system name itself is not included in this process. -Then the command is executed as usual. -.pg -The second flag available if the news system is built with -.b MULTICAST -defined is -.b O . -If this flag is set, -then the sys file line will be ignored unless the system name is -a multicast name from some earlier line with the -.b M -flag, -and the news item is to be sent to that (earlier) system. -This allows the subscription list for the multicast system name -(which is likely to be a fake system name, -invented just for this purpose) -to be given a very wide subscription list -(like -.ng all ) -without any unusual effects. -.pg -Here is an example. -Assume that you wish to forward -.ng comp.unix -to four people by mail. -You could do this as ... -.si -.sd -fred:comp.unix::mail fred -harry:comp.unix::mail harry -jane:comp.unix::mail jane -tony:comp.unix::mail tony -.ed -.ei -however this causes the mail program to be started 4 times, -once for each recipient. -On some systems starting the mail program is a very expensive operation. -If -.b MULTICAST -is defined, -an alternative method is -.si -.sd -fred:comp.unix:M:tony -harry:comp.unix:M:tony -jane:comp.unix:M:tony -tony:comp.unix::mail tony %s -.ed -.ei -This would cause just one command to be run: -\*(lqmail tony fred harry jane\*(rq. -Note that \*(lqtony\*(rq must still be explicitly included in the argument -list to the mail command; -the \*(lq%s\*(rq does not expand to include -the multicast \*(lqsystem name\*(rq itself. -.pg -A more useful way of doing this, -which does not assume that all the mail readers -will want to read the same newsgroups is as follows. -.si -.sd -fred:comp.unix:M:Mail -harry:sci.physics,sci.astro:M:Mail -jane:comp.unix.wizards,soc.women:M:Mail -tony:comp.unix,comp.unix.wizards,rec.humor:M:Mail -Mail:all:O:mail %s -.ed -.ei -.pg -Now, -if a news item in group -.ng comp.unix -was received, -the command -.sd c -mail fred tony -.ed -would be executed. -If the news were in both -.ng comp.unix -and -.ng comp.unix.wizards -then the command would be -.sd c -mail fred jane tony -.ed -.pg -If a news item in -.ng sci.med -(which no-one gets by mail) arrives, -then the \*(lqMail\*(rq line will be ignored, -because of the -.b O -flag. -\*(lqMail\*(rq is a fake system invented just so its \*(lqtransfer command\*(rq -can be used to send news to the other recipients. -.pg -The same kind of technique can be used for normal transfer -of news to other systems if your transport network supports -a facility to send to many other systems in one command. -(That is, -if it has a multicast facility.) -SunIII (the network used in Australia) has this ability, -so a typical Australian -.i sys -file looks like -.sd -emuvax:world,aus,comp.sci:M:FakeName -kremlin:world,aus,comp,sci:M:FakeName -kanga:world,aus,comp.unix:M:FakeName -FakeName:all:OUS:/bin/sendfile -NRSareporter -d%s -x%s -.ed -.pg -A news item in -.ng aus.general -causes the following command -.sd c -/bin/sendfile -NRSareporter -demuvax -dkremlin -dkanga -x/usr/spool/... -.ed -to be executed. -Just one command is run to send the news to three remote systems. -.pg -If a multicast system has the -.b F -flag set, -then the name of a file containing the news is appended to the file -whose name is in the fourth field, -as usual. -But on the same line, -separated by spaces, -will be appended the names of all the systems -that referenced this multicast system. -.pg -For example, -if the Australian site wanted to batch news, -instead of sending it directly, -it would simply change the last line of its -.i sys -file to -.sd c -FakeName:all:F:/usr/spool/batched/allsites -.ed -.pg -Then a news item in -.ng misc.jobs -would cause the following line to be appended to -.i /usr/spool/batched/allsites -.sd c -/usr/spool/news/misc/jobs/5542 emuvax kremlin -.ed -.pg -This can then be processed later, in something like the normal manner. -(Unfortunately no commands to do this processing are yet available.) -.pg -Caution: when -.b MULTICAST -is defined, -the first \*(lq%s\*(rq in all transfer commands is used for multicast, -regardless of whether or not the system name is ever used as the last field -of some line with the -.b M -flag set. -To use the -.b U -flag in such a case, -a dummy \*(lq%s\*(rq should be used, -it will simply be omitted from the command that is executed. -.pg -As an example, -if a -.i sys -file line without -.b MULTICAST -defined was: -.sd c -foovax:comp,world,na,usa:U:uux - foovax!foonews <%s -.ed -with -.b MULTICAST -defined, -it would need to be changed to: -.sd c -foovax:comp,world,na,usa:U:uux - foovax!foonews %s <%s -.ed -.pg -Additional caution: -The numbers of system names that may be used -in this way are quite severly restricted. -Typically there may only be about 10 multicast system names, -and each of those is restricted to sending to no more than about 20 systems. -These limits are dynamic -(that is, -the numbers counted are the number of multicast systems -receiving any single news item, -and the number of systems that each of those -will actually cause this particular news item to be sent to). -These limits should easily suffice for real news sending to remote systems; -however they are not likely to suffice if you want to mail news to everyone -on your host. -.bp -.hu -Appendix C: Installing news on a Eunice system -.pg -Eunice does not have links. To get around this problem without -wasting megabytes of disk space, links are simulated. Each article -is stored under the directory corresponding to the first group on -the Newsgroups line. The remaining directories contain a short -file giving the name of the real file. -.i Readnews -and -.i vnews -know how to follow these links; so does -.i rn -if it is compiled with -.b LINKART -defined -.i rn "" ( -is not included in this distibution). -.pg -If you expire different groups at different times, an article disappears -when the first group in the Newsgroups line expires, even if it's cross -posted to a group you retain longer. Also, the archival option for -.i expire -(\-a flag) does not work. -.pg -Eunice does not have the set-user-id bit. Instead, the VMS feature -allowing installation of privileged images is used. inews and rnews -must be installed with SYSPRV privilege. To allow VMS to install -.i inews -.i rnews "" ( -is a copy of it), it must be linked with the -.i /notrace -flag. Despite the documentation, this only seems to work if the -VMS linker is used on VMS-format object files, as of Eunice version 4.2. -So it is VERY IMPORTANT to type -.i vmsobj -before building news. -.pg -The DCL command file -.i euninstal.com -installs -.i inews -and -.i rnews -with the proper privileges. It is run by \*(lqmake install\*(rq as the last -step. It is possible that it will fail because your system does -not have sufficient global page table space or known file list -entries. See the Eunice installation manual to learn how to increase -the values of these parameters (you will have to reboot the system). -.pg -The -.i euninstal.com -script must be run every time the system is booted. -I suggest invoking it from /etc/suchmod.com. -.pg -It is crucial that -.b LIBDIR \f2/active\fP -and -.b LIBDIR \f2/seq\fP -be in Unix format, as opposed to VMS format. Use -.i etc/vmstounix -to assure this. -.pg -Not all options have been tested; if you select options other than -those set by the localize.vms script (except for obvious things like -.B ORGNAME , -etc) I can't guarantee that it will work. In particular, I -haven't attempted to define -.b SPOOLNEWS -or -.b MULTICAST . -That doesn't mean they won't work, just that I haven't tried them. -.pg -If you choose to run compressed batching, I recommend that you put -.i cunbatch -in your -.i L.cmds -file and have your news feed send -compressed batches the \*(lqold\*(rq way, because this saves an exec, and -forks and execs are so expensive on Eunice (the new way is for the -first line to be #cunbatch, and have -.i rnews -exec -.i cunbatch ). -.pg -If you have questions on Eunice and news contact: -.sd c -Joe Buck, Entropic Processing, Inc. -.sp 1 -seismo!epiwrl!epimass!jbuck -hplabs!oliveb!epimass!jbuck -.ed *-*-END-of-install.mn-*-* exit
sources-request@mirror.UUCP (10/31/86)
Submitted by: seismo!rick (Rick Adams) Mod.sources: Volume 7, Issue 47 Archive-name: 2.11news/Part07 # To extract, sh this file # # news 2.11 documentation File 5 of 6 # if test ! -d doc then mkdir doc fi if test ! -s doc/install.mn then echo "First half of doc/install.mn is missing. shar aborted" exit 1 fi echo "x - doc/install.mn (second half)" 1>&2 sed 's/.//' >>doc/install.mn <<'*-*-END-of-install.mn-*-*' -.hn 1 -Format of the -.bi sys -file -.pg -To set up a link to another site, -edit the -.i sys -file in -.b LIBDIR . -This file is similar to the -.i L.sys -file of UUCP. -E