Return to b.interface CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 11.notes

Annotation of 43BSDReno/share/doc/usd/11.notes/b.interface, revision 1.1

1.1     ! root        1: .\"    @(#)b.interface 6.1 (Berkeley) 5/26/86
        !             2: .\"
        !             3: .ls 1
        !             4: .ap B "Interfacing Notesfiles to News"
        !             5: 
        !             6:        The News system provides functions similar to
        !             7: those provided by the Notesfile system.
        !             8: It is possible to gateway articles between the two systems.
        !             9: In USENET, a common configuration is for several notesfiles
        !            10: sites to form a subnetwork of USENET and
        !            11: gateway articles between the local notesfile network and
        !            12: the rest of USENET.
        !            13: These articles propogate across USENET in the news system.
        !            14: Article originating in the news system are gatewayed into
        !            15: the notesfile network.
        !            16: When several notesfile networks exist as subnetworks of
        !            17: a larger news network (such as USENET), articles written
        !            18: in one notesfile network will be correctly interpreted
        !            19: when arriving at another notesfile network.
        !            20: ``Correctly'' interpreted includes proper linking of
        !            21: responses to their true parents;
        !            22: this is sometimes not possible with articles written in the
        !            23: news system.
        !            24: 
        !            25:        The notesfile gateway code recognizes articles meeting
        !            26: the USENET standards.
        !            27: Additionally, the A-news protocol and older B-news protocols
        !            28: are recognized.
        !            29: Incoming (news \(-> notes) articles are parsed and placed in the
        !            30: appropriate notesfiles.
        !            31: Articles written within a notesfile subnetwork are formatted according
        !            32: to USENET standards and transmitted to the news system.
        !            33: 
        !            34: .a1 "Configurations for Sites without News"
        !            35: 
        !            36:        Sites running notesfiles without the news program have
        !            37: several possible configuations.
        !            38: If your site is part of a notesfile subnetwork and you wish to
        !            39: have your articles gatewayed to the news system and the
        !            40: rest of USENET, you must find a site who will act as a 
        !            41: gateway for your articles.
        !            42: The gateway code performs its task in such a way as to allow
        !            43: several sites to gateway the same article into the news system;
        !            44: the multiple copies will have identical unique identifiers 
        !            45: and one copy will be canceled when they meet on a remote system.
        !            46: 
        !            47: .a2 "Sites with no News Neighbors"
        !            48: 
        !            49:        If you have no immediate neighbor running news, there is
        !            50: no particular action you should take other than to reassure
        !            51: yourself that some site in the notesfile subnetwork is gatewaying
        !            52: notes-generated articles to the news system.
        !            53: This can be done in one of several ways.
        !            54: If the site wants to gateway articles specifically from your
        !            55: machine, the following command should be executed on that site
        !            56: occasionally. This is typically done through cron(8).
        !            57: 
        !            58:        newsoutput -syoursite notesfile-list
        !            59: 
        !            60: A more typical arrangement is where the gateway site sends all
        !            61: notes-generated articles that arrive on its system into the 
        !            62: news system.
        !            63: In this case, the gateway site will execute a command such as 
        !            64: the following:
        !            65: 
        !            66:        newsoutput -a notesfile-list
        !            67: 
        !            68: A site gate using this command line will automatically gateway
        !            69: articles written at your site and eliminates the need of running
        !            70: a command similar to the first command line.
        !            71: 
        !            72: 
        !            73: .a2 "Sites with Neighbors running News"
        !            74: 
        !            75:        If a neighboring system runs both notes and news, you
        !            76: have the option of gatewaying your own articles or allowing
        !            77: the neighbor to gateway articles for you.
        !            78: If the neighbor does not run the notesfile system, you must
        !            79: provide your own gateway functions.
        !            80: 
        !            81:        Gatewaying can be done similarly to the site without
        !            82: a news neighbor.  You can let your articles propogate across
        !            83: a notesfile network to a gateway site which will send them
        !            84: to the news system.
        !            85: Another option is to gateway your articles,
        !            86: and possibly any notesfile-generated articles,
        !            87: into the news system at the neighboring site.
        !            88: This gets your articles into USENET as quickly as possible.
        !            89: The two options are not mutually exclusive;
        !            90: you can gateway your own articles and allow another site to
        !            91: gateway them.
        !            92: When copies of the same article meet on a news system, the
        !            93: extra copy will be removed from the network.
        !            94: 
        !            95:        To gateway articles into news, you must modify the
        !            96: file
        !            97: /usr/spool/notes/.utilities/net.how
        !            98: to tell the newsoutput
        !            99: program how to get to the news system.
        !           100: More information on this can be found in the section
        !           101: ``Copying Notesfiles to News'' later in this appendix.
        !           102: 
        !           103:        To gateway from the news system to the notesfile
        !           104: system, you must arrange to have the news system at the remote
        !           105: site send articles as standard input to the program
        !           106: /usr/spool/notes/.utilities/newsinput 
        !           107: on your system.
        !           108: 
        !           109:        Information on mapping functions between notesfiles
        !           110: and news, how to configure a news system to send articles to
        !           111: a notesfile system,
        !           112: and
        !           113: how to have a notesfile system send articles to a news system
        !           114: can be found later in this appendix.
        !           115: 
        !           116: .a1 "Configurations for Sites running News"
        !           117: 
        !           118:        A site running both notesfiles and news will typically
        !           119: perform gateway functions in both directions,
        !           120: from the notesfile system to the news system
        !           121: and
        !           122: from the news system to the notesfile system.
        !           123: In these cases all the operations are local.
        !           124: 
        !           125: .a1 "Gatewaying between Notesfiles and News"
        !           126: 
        !           127:        The two notesfile programs ``newsoutput'' and ``newsinput''
        !           128: perform gatewaying between notesfile and news systems.
        !           129: Newsoutput takes notesfile-generated articles, formats them,
        !           130: and hands them to the news system.
        !           131: Newsinput takes articles from the news system and inserts
        !           132: them in the notesfile system.
        !           133: 
        !           134: .a2 "Copying News to Notesfiles"
        !           135: 
        !           136:        The news system maintains ``subscription lists'' for
        !           137: each neighboring system.
        !           138: The subscription list is stored in the file /usr/lib/news/sys
        !           139: on a B-news system.
        !           140: On an A-news system, the subscription list is in 
        !           141: /usr/spool/news/.sys
        !           142: 
        !           143:        News feeds articles to neighboring systems as they 
        !           144: arrive.
        !           145: In many cases, the article is queued for transmission.
        !           146: In other cases, the article is given to a batching program
        !           147: which collects a number of articles for transfer
        !           148: and sends them to an appropriate un-batching program at
        !           149: the receiving end.
        !           150: 
        !           151:        In the case where the notesfile system resides on another
        !           152: machine, the news subscription line should be generated similarly
        !           153: to that for a normal news feed with several exceptions.
        !           154: The first is that the newsinput program does not understand about
        !           155: batching; articles must be sent one at a time.
        !           156: Also, one must specify the method of transmitting the article.
        !           157: To feed the system ``somesite'' with news, the
        !           158: neighbor will add a line of the following form to his /usr/lib/news/sys:
        !           159: 
        !           160:        somesite:subscription::uux - -n somesite!/usr/spool/notes/.utilities/newsinput
        !           161: 
        !           162: Of course, networks other than UUCP can be used.
        !           163: 
        !           164:        To forward to a notesfile system on the same machine as the
        !           165: news system, create a pseudo site which doesn't exist elsewhere
        !           166: (a sitename such as ``nf_sys'' works), and add a line like:
        !           167: 
        !           168:        nf_sys:subscription::/usr/spool/notes/.utilities/newsinput
        !           169: 
        !           170: Articles arriving at the local system will now be forwarded to
        !           171: the notesfile system.
        !           172: By default, news articles are placed in notesfiles with the
        !           173: same name.
        !           174: To map newsgroups to particular notesfiles, see the later
        !           175: section ``Naming Notesfiles and Newsgroups''.
        !           176: 
        !           177: .a2 "Copying Notesfiles to News"
        !           178: 
        !           179:        The newsoutput program transfers notesfile-generated
        !           180: articles from the notesfile system to a news system.
        !           181: The news system does not have to be on the same machine.
        !           182: 
        !           183:        Newsoutput accepts parameters telling it to gateway
        !           184: articles from specific systems or any system.
        !           185: Additional options allow backwards compatible
        !           186: headers for older versions of the notesfile software.
        !           187: A typical newsoutput invocation looks like:
        !           188: 
        !           189:        newsoutput -a notesfile-list
        !           190: 
        !           191: The -a parameter indicates that notesfile generated articles
        !           192: from any site are to be sent to the news system.
        !           193: Under no circumstances will newsoutput transfer an article
        !           194: to the news system if it has passed through the news system
        !           195: before.
        !           196: Thus if a notes generated article passes from one notesfile
        !           197: subnetwork to another through the news system, the 
        !           198: article will not be sent into the news system by anyone in 
        !           199: the second notesfile subnetwork.
        !           200: 
        !           201:        The ``notesfile-list'' can contain a mixture of
        !           202: specific notesfiles, wild-card specifications (net.*),
        !           203: or ``-f file'' parameters which specifies a file
        !           204: containing a list of notesfiles to send.
        !           205: 
        !           206:        Alternatively, articles for only one system can be
        !           207: gatewayed with a command line of the form:
        !           208: 
        !           209:        newsoutput -ssitename notesfile-list
        !           210: 
        !           211: This invocation method maintains a sequencer for each system;
        !           212: the -a option maintains a single global sequencer.
        !           213: 
        !           214:        A third invocation method of newsoutput uses the
        !           215: ``-c'' option and specifies a specific set of systems to
        !           216: gateway articles for.  The command looks like:
        !           217: 
        !           218:        newsoutput -c gateway-site-file notesfile-list
        !           219: 
        !           220: The ``gateway-site-file'' specifies a file containing a list
        !           221: of sitenames.
        !           222: Articles written at any of these sites are gatewayed to the
        !           223: news system.
        !           224: Thus newsoutput has the ability to send articles to news
        !           225: for a single system, several systems, or any system.
        !           226: 
        !           227:        Newsoutput assumes that a news system is installed
        !           228: on the local system.
        !           229: If the news system is in a non-standard location on the
        !           230: local system or
        !           231: the news system is on a different machine, newsoutput
        !           232: can be told where to send articles.
        !           233: The file /usr/spool/notes/.utilities/net.how contains
        !           234: command templates for notesfile networking.
        !           235: To specify a non-standard place for the ``rnews'' program,
        !           236: add a line of the form:
        !           237: 
        !           238:        Usenet:x:::uux - -n myneighbor!/usr/bin/rnews
        !           239: 
        !           240: Non-UUCP connections and the like can be specified.
        !           241: 
        !           242: .a2 "Naming Notesfiles and Newsgroups"
        !           243: 
        !           244:        Notesfiles and newsgroups for the same topic can have
        !           245: different names.
        !           246: Notesfiles are currently limited in the last component of
        !           247: their name to the length of a filename;
        !           248: under V7, System III, System V, and 4.1 Bsd this is 14
        !           249: characters.  4.2 Bsd extends the length of a filename
        !           250: to a maximum of 255 characters per component.
        !           251: Newsgroup names are no longer limited in total length;
        !           252: the only restriction in current news versions is
        !           253: that each component (between .'s) is unique in
        !           254: the first 14 characters.
        !           255: 
        !           256:        The file ``/usr/spool/notes/.utilities/newsgroups''
        !           257: defines the relationships between notesfiles and newsgroups.
        !           258: Lines in the file have the general form:
        !           259: 
        !           260:        notesfile:base_newsgroup:respone_newsgroup
        !           261: 
        !           262: Lines beginning with the ``#'' character are considered
        !           263: comment lines.
        !           264: The ``response_newsgroup'' field and the colon separating
        !           265: it from the base_newsgroup field are optional.
        !           266: 
        !           267:        Entries in this file need be made for only a few reasons:
        !           268: (1) The newsgroup which matches the notesfile is longer than fourteen
        !           269: characters,
        !           270: (2) the notesfile and the newsgroup are different names
        !           271: (e.g. the notesfile `Bnews' can be linked to the newsgroup `net.news.b'
        !           272: with an entry of `Bnews:net.news.b'),
        !           273: (3) you want several newsgroups linked to a single notesfile,
        !           274: and
        !           275: (4) notes and responses from a notesfile should go to
        !           276: different newsgroups (net.general/net.followup is one example).
        !           277: The file is scanned from the beginning until EOF or a match is found.
        !           278: When no match is found, the code returns the original argument as if
        !           279: it had matched itself.
        !           280: The process is similar to having placed a sentinel line of the
        !           281: form:
        !           282: 
        !           283:        myarg:myarg
        !           284: 
        !           285: at the end of the file.
        !           286: 
        !           287:        The optional third field in the line is used to send 
        !           288: notes and responses from a notesfile to separate newsgroups.
        !           289: The net.general/net.followup convention is an example of
        !           290: how this would be used.
        !           291: Typically the net.general and net.followup newsgroups are
        !           292: mapped into the same notesfile.
        !           293: To preserve peace with news users, responses written in a
        !           294: notesfile `net.general' should go to the newsgroup `net.followup'.
        !           295: The following pair of lines will map all news from net.general
        !           296: and net.followup into the notesfile net.general. 
        !           297: Base notes from the notesfile net.general will go to the newsgroup
        !           298: net.general;
        !           299: responses in the net.general notesfile will be sent to
        !           300: the net.followup newsgroup.
        !           301: 
        !           302: .nf
        !           303:        net.general:net.general:net.followup
        !           304:        net.general:net.followup
        !           305: .fi
        !           306: 
        !           307: The first line maps news in net.general to the notesfile net.general.
        !           308: It also does the mapping from notesfiles to newsgroups.
        !           309: The second line maps news from net.followup into the notesfile
        !           310: net.general.
        !           311: Note that the response field is not used in the mapping from
        !           312: newsgroups to notesfiles; it is used only for mapping notesfile
        !           313: responses into a different newsgroup.
        !           314: 
        !           315:        To map several newsgroups into the same notesfile, 
        !           316: place lines of the following form in the ``newsgroups'' file:
        !           317: 
        !           318: .nf
        !           319:        somenotesfile:newsgroup1
        !           320:        somenotesfile:newsgroup2
        !           321: .fi
        !           322: 
        !           323: If you wish to have articles from the notesfile ``somenotesfile''
        !           324: go to both of the newsgroups, insert a line before the above lines
        !           325: to map articles going to notesfiles.
        !           326: The result would look like:
        !           327: 
        !           328: .nf
        !           329:        somenotesfile:newsgroup1,newsgroup2
        !           330:        somenotesfile:newsgroup1
        !           331:        somenotesfile:newsgroup2
        !           332: .fi
        !           333: 
        !           334: The first line is the one used for articles going from notesfiles
        !           335: to news; the newsgroups specification ``newsgroup1,newsgroup2''
        !           336: is used on those articles.
        !           337: Articles coming from the newsgroup ``newsgroup1'' will fail to
        !           338: match the first line, since the program expects exact matching.
        !           339: They will match the second line and be mapped to the 
        !           340: notesfile ``somenotesfile''.
        !           341: 
        !           342: .a1 "Typical Configurations"
        !           343: 
        !           344:        A typical notesfile subnetwork contains a number of
        !           345: pure notesfile sites and several sites running both news and
        !           346: notesfiles.
        !           347: In these situations, some subset of the sites running
        !           348: both notes and news
        !           349: act as gateway sites.
        !           350: The pure notesfile sites don't concern themselves with 
        !           351: gateway operations.
        !           352: The gateway sites typically gateway all notes-generated
        !           353: articles to news.
        !           354: Duplicate articles, gatewayed at several sites,
        !           355: will propogate across the news network.
        !           356: When two or more of these articles meet at some site, the
        !           357: superflous copy will be removed from the network.
        !           358: 
        !           359:        If none of the sites in the notesfile subnetwork
        !           360: run the news program,
        !           361: the gateway site will be one or more of the sites having
        !           362: neighbors that do run news.
        !           363: These gateway sites will run newsoutput and direct the
        !           364: output to the news site by making the appropriate
        !           365: entry in /usr/spool/notes/.utilities/net.how
        !           366: for the pseudo-site ``Usenet''.
        !           367: 
        !           368: .a1 "News Gateway Installation Checklist"
        !           369: 
        !           370:        The following checklist covers the variables in the
        !           371: ``newsgate.h'' file which may need to be changed on your system.
        !           372: It also mentions which files to modify to automate the transfer
        !           373: of articles between the two systems.
        !           374: 
        !           375: .bz
        !           376: .iz
        !           377: [edit] src/newsgate.h
        !           378: .iz
        !           379: MYDOMAIN.
        !           380: This should be set to the domain your site is in.
        !           381: Typical domains are ``UUCP'' and ``ARPA''.
        !           382: .iz
        !           383: DFLTRNEWS.
        !           384: The news receiving program. 
        !           385: This can normally be left as is;
        !           386: alternate news insertion methods can be specified
        !           387: with more flexibility through the net.how file.
        !           388: .iz
        !           389: EXPANDPATH.
        !           390: If defined, the code looks in the file specified
        !           391: by PATHMAP for a route to an author's system.
        !           392: The code which does this is in ``src/newspath.c''
        !           393: and expects a particular format in the PATHMAP 
        !           394: file.
        !           395: You may wish to replace it with code of your own if
        !           396: your data base is in a different format.
        !           397: .iz
        !           398: PATHMAP.
        !           399: This is the full pathname of the routing tables
        !           400: used if EXPANDPATH is defined.
        !           401: .iz
        !           402: [finished editing] src/newsgate.h
        !           403: .iz
        !           404: make newsouput newsinput.
        !           405: This will recompile the notesfile/news gateway programs.
        !           406: .iz
        !           407: Check /usr/lib/news/sys
        !           408: to see that news will be forwarded to the notesfile system.
        !           409: .iz
        !           410: Make entries in /usr/lib/crontab to
        !           411: invoke newsoutput occcasionally.
        !           412: We use every 6 hours.
        !           413: .iz
        !           414: If the news system is on another machine or in a non-standard
        !           415: place,
        !           416: modify 
        !           417: /usr/spool/notes/.utilities/net.how.
        !           418: Add a pseudo-site ``Usenet'' which specifies how to
        !           419: get to the remote machine.  One example is:
        !           420: .br
        !           421:        Usenet:x:::uux - -z neighbor!/usr/bin/rnews
        !           422: .iz
        !           423: Check /usr/spool/notes/.utilities/newsgroups.
        !           424: A sample of how this file will look is included in the
        !           425: ``Samples'' directory of the distribution.
        !           426: .iz
        !           427: Everything should be configured now.
        !           428: You will probably want to run several tests on local
        !           429: or limited distribution newsgroups to satisfy yourself
        !           430: that it works.
        !           431: .ez

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.