v07i047: 2.11 News Documentation and Conversion, Part07/08

[sources-request at mirror.UUCP]

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