Return to b.interface CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / notes / doc

Annotation of 43BSDTahoe/new/notes/doc/b.interface, revision 1.1

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

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