home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / ng030.zip / ngate.doc < prev    next >
Text File  |  1996-09-16  |  15KB  |  419 lines
  1.                          nGate 0.3
  2.  
  3.                Copyright (c) Dave Hamilton 1995, 1996
  4.  
  5.  
  6.  
  7.  
  8.                         WARNING
  9.  
  10.     This is freeware. It is not guaranteed to do anything, or
  11.     to not do anything. Use it at your own risk.
  12.  
  13.     Future versions, as features are added, may become shareware.
  14.     It is my hope that I can maintain a pre 1.0 version as freeware
  15.     always, and add a post 1.0 version as shareware that will simply
  16.     be more functional. I intend to have two versions. Have fun with
  17.     this one.
  18.  
  19.  
  20. Acknowledgements
  21.  
  22.     OS/2, Warp, and IBM's version of SENDMAIL are copyright (c) IBM Corp.
  23.     Msgapi32.dll and Squish are copyright (c) SCI Communications, and are
  24.     trademarks of Lanius Corporation.
  25.     FleetStreet is copyright (c) by Michael Hohner and Harry Herrmannsdorfer.
  26.     MailGate is copyright (c) by Dave Hamilton.
  27.  
  28. 1.0 Changes
  29.  
  30.     0.30 Increased line buffer size. It was crashing on headers with
  31.          very long newsgroups: entries.
  32.  
  33.          Made date routine yet smarter.
  34.  
  35.     0.20 Made config file reader a little more intelligent, was crashing
  36.          and in some cases linking the wrong area with newsgroup
  37.  
  38.          Changed Date on posted articles to conform with more news
  39.          servers.
  40.  
  41.          Increased logging information
  42.  
  43.          Now rewrites newsrc file after each group is received instead
  44.          of after entire retrieval
  45.  
  46.          Fixed buffer overrun when very long list of Newsgroups: was
  47.          read, causing trap 05 crash
  48.  
  49.     0.10 First Beta Release
  50.  
  51.  
  52. 1.1    What is nGate?
  53.  
  54.     nGate (NewsGate) is a simple program that acts as an interface between
  55.     an nntp news server and your Squish message base. It was designed as
  56.     a companion program for MailGate, but kept apart from it so that
  57.  
  58.         1) a simple version could be distributed as freeware
  59.         2) both MailGate and nGate could remain simple
  60.  
  61.     nGate retrieves unread news articles from an nntp server that you
  62.     are connected to and tosses them into your Squish message base.
  63.     nGate also scans messages from your Squish message base and
  64.     posts them to an nntp news server.
  65.  
  66.     Once messages are in your message base, they may be read by
  67.     you or your users. Depending upon how you have your BBS configured,
  68.     your users may post responses or new messages in those areas.
  69.  
  70.     See section 4.0 for some history of how nGate evovled and how
  71.     the author has it configured on a busy system.
  72.  
  73. 1.2 Requirements
  74.  
  75.     You must be running OS/2 version 3.0 (Warp) or above.
  76.  
  77.     At the time  you run nGate, you must be connected to an internet
  78.     provider service (ISP) and have access to a news server that uses the
  79.     NNTP protocol. Finally, you must have a message base that is
  80.     either Squish or *.MSG (Star-dot-Message).
  81.  
  82.     nGate does not create any temporary files when working; it relies
  83.     on OS/2's virtual memory and handles one news article at a time.
  84.     The more memory your machine has, the better for every program
  85.     you run, but nGate will run safely in any amount of memory that
  86.     OS/2 can run in.
  87.  
  88. 1.3 Files and Directories
  89.  
  90.     nGate requires two files to run:
  91.  
  92.         newsrc
  93.         ngate.cfg
  94.  
  95.     The newsrc file is a list of newsgroups that you are interested
  96.     in or "subscribed to".
  97.  
  98.     The ngate.cfg file is nGate's configuration file (big surprise)
  99.     containing basic configuration information and a list of
  100.     newsgroups along with the message bases that are associated
  101.     with them.
  102.  
  103.     To locate these files, nGate searches in the following order:
  104.  
  105.         1) the environment variable MAILGATE
  106.         2) the current directory
  107.  
  108.     Please note the order. If you have a line in your config.sys
  109.     such as:
  110.  
  111.         SET MAILGATE=C:\MG
  112.  
  113.     nGate will look in c:\mg for its files before it looks in the
  114.     directory you are in when it runs.
  115.  
  116.     nGate can create a log file that records its actions. If you
  117.     run it with the logging option on, it creates the log file
  118.     called ngate.log in the same directory as its two files.
  119.  
  120. 1.3 Setting Up
  121.  
  122.     If you are already using MailGate, and have the MAILGATE environment
  123.     variable set, it is suggested you copy nGate.exe to that directory
  124.     and create your configuration files there. If not, create a
  125.     directory (it doesn't have to be at the root of the drive) and
  126.     create your configs in that directory. When you run nGate, change
  127.     to that directory.
  128.  
  129.     If you don't already have MSGAPI32.DLL on your system, copy the
  130.     one enclosed to somewhere in your LIB path. OS2\DLL is usually
  131.     a good place to put it.
  132.  
  133. 1.4 The newsrc File
  134.  
  135.     Using a text editor, create a file called "newsrc" (without the
  136.     quotes, no file extension). Create one line for each newsgroup
  137.     you want, ending with a colon. Example:
  138.  
  139.         comp.os.os2.advocacy:
  140.         comp.os.os2.bugs:
  141.  
  142.     Each time nGate runs, it will read this file, and it will UPDATE
  143.     this file with the low and high article number pointers from the
  144.     server. After nGate has run, your newsrc file will look something
  145.     like this:
  146.  
  147.             comp.os.os2.advocacy: 23413-25752
  148.             comp.os.os2.bugs: 7361-7407
  149.  
  150.     You can add a new group any time you like. It is the colon that
  151.     causes nGate to query the server for new articles, and the existing
  152.     numbers that let nGate and the server to know which articles you
  153.     haven't received yet.
  154.  
  155.     Note that nGate uses a conventional newsrc file common to many
  156.     Unix and OS/2 applications. If you are installing nGate along with
  157.     or in place of, another news reader, you may be able to use an
  158.     existing file. Most newsreaders we've seen use this format.
  159.  
  160. 2.1 ngate.cfg
  161.  
  162.     This file is also created with a text editor. The first few lines
  163.     describe environment information. These are followed by one line
  164.     for every news group you subscribe to.
  165.  
  166.     Here's an example file:
  167.  
  168.         from            1:229/622.0            ; From node
  169.         to                All                    ; To: field
  170.         origin            "Serenity Base"        ; for in and out msgs
  171.         domain             sbase.com            ; for outbound
  172.         newsserver        leebeach.sbase.com    ; our news server's address
  173.         
  174.         alt.als  $L:\Max\News\7003
  175.         alt.religion.scientology $L:\Max\News\1999
  176.         comp.os.os2.comm   $L:\Max\News\5006 
  177.         comp.os.os2.games   $L:\Max\News\5007 
  178.         comp.os.os2.mail-news   $L:\Max\News\5008
  179.         comp.os.os2.marketplace   $L:\Max\News\5009
  180.         comp.os.os2.misc   $L:\Max\News\5010 
  181.         comp.os.os2.multimedia   $L:\Max\News\5011
  182.         comp.os.os2.networking   $L:\Max\News\5012
  183.         comp.os.os2.networking.misc   $L:\Max\News\5013
  184.         
  185.     You can probably figure out most of the config file from the
  186.     example above, but we'll go over each of the lines just in
  187.     case.
  188.  
  189.     Blank lines are ignored.
  190.  
  191.     A semicolon and everything to the right of it is ignored. You can
  192.     (and are encouraged to) use semicolons to comment the lines in
  193.     your file, or to 'comment-out' lines you with to temporarily
  194.     turn off.
  195.  
  196. 2.2 From
  197.  
  198.     This is the fido or network address of your own system. It is
  199.     used for incoming articles to fill in the 'from' address, because
  200.     FIDO requires such address to be present. From a working perspective
  201.     it doesn't do anything at all, but it must be entered.
  202.  
  203. 2.3 To
  204.  
  205.     As above, this field must be filled in, or some message readers
  206.     will lose their minds. 'All' is probably the best choice here,
  207.     given the nature of usenet.
  208.  
  209. 2.4 Origin
  210.  
  211.     This field serves two purposes. On inbound mail, it takes on a
  212.     role similar to above, and just fills in a field in the message.
  213.  
  214.     For outbound articles, it is used for the 'Organization:' field
  215.     in articles posted from your system to usenet.
  216.  
  217.     Unless you can think of anything better, this would normally be
  218.     the name of your BBS.
  219.  
  220. 2.5 Domain
  221.  
  222.     This is the domain name of your BBS. It is used by nGate to
  223.     generate an email address for the person posting articles
  224.     from your system to usenet. Some message editors such as
  225.     FleetStreet let you use a complete email address in the
  226.     From field. Others insist on first/last names, or aliases.
  227.  
  228.     When nGate is scanning outbound messages, it looks at the
  229.     'from' field to see if it contains an atpersand (@). If it
  230.     does, the field is used as-is. If not, the contents of the
  231.     field are trimmed of leading and trailing spaces, internal
  232.     spaces are converted to dots, and it is converted to lower
  233.     case. Then, the atpersand is appended, followed by this
  234.     Domain name.
  235.  
  236.     For example, assume you have this configured:
  237.  
  238.         domain my-bbs.com
  239.  
  240.     Here's what nGate will do with the names of these posters:
  241.  
  242.         Finds                    Changes to
  243.         -----                    ----------
  244.         alvin@my-bbs.com        alvin@my-bbs.com
  245.         Squeaky                    squeaky@my-bbs.com
  246.         Harry Armes                harry.armes@my-bbs.com
  247.  
  248. 2.6 newsserver
  249.  
  250.     This is the tcp/ip address of the news server you will connect
  251.     to. Example:
  252.  
  253.         rosie.sbase.com
  254.  
  255.     Note that ISP's can configure their servers so that you can have
  256.     read-only access, read-and-post access, or no access.
  257.  
  258.     When nGate first connects with the server it will determine access
  259.     from the server. If you don't have posting permission and you
  260.     attempt to post articles to the server, nGate will tell you so.
  261.     If you operate within the access you have, nGate will not report
  262.     anything. If nGate is silent, everything's working.
  263.  
  264. 2.7 newsgroup <-> message base lines
  265.  
  266.     These lines consist of a newsgroup name, one or more spaces,
  267.     and the path to the message base associated with the newsgroup.
  268.  
  269.     If the message base is Squish, the path will begin with a
  270.     dollar sign ($).
  271.  
  272.     If the message base is *.MSG, just provide the path.
  273.  
  274.     Example:
  275.  
  276.         comp.os.os2.comm   $L:\Max\News\5006 
  277.  
  278. 3.1 Running nGate
  279.  
  280.     Ok, let's assume you have your config files set up. Change to
  281.     the directory where nGate and its config files live.
  282.  
  283.     To IMPORT articles, type:
  284.  
  285.         ngate -i
  286.  
  287.     nGate will connect to the server and process all lines you
  288.     have entered in your newsrc file. For each line, it will locate
  289.     your Squish or *.MSG message base, and query the server for any
  290.     new articles. As it runs, it will display the newsgroup it is
  291.     currently working on, the number of new articles to be downloaded,
  292.     and its progress as it downloads them and tosses them into your
  293.     message base. When it has downloaded all the articles, it will
  294.     return to the OS/2 command prompt.
  295.  
  296.     To send OUTBOUND articles, type:
  297.  
  298.         ngate -o
  299.  
  300.     nGate will connect to the server and determine that you do have
  301.     posting access. Next it will process each message base you have
  302.     configured, scanning for newly entered messages. As it finds
  303.     them, it will post them to the newsserver and mark them as
  304.     SENT in your message base. nGate will display a line for each
  305.     newsgroup it is processing, and if there are any articles to post,
  306.     will display a count of posted articles. Depending upon your
  307.     hardware and memory, it may take several seconds or longer to
  308.     scan each message area.
  309.  
  310.     If you want to process INBOUND and OUTBOUND articles on the
  311.     same pass, type:
  312.  
  313.         ngate -i -o
  314.  
  315.     nGate will process INBOUND first, then OUTBOUND.
  316.  
  317. 3.2 Logging
  318.  
  319.     To turn on logging (recommended), add the -l switch to your
  320.     command. For example, to import articles with logging, type:
  321.  
  322.         ngate -i -l
  323.  
  324.     As newer versions of nGate are released, more detail will be
  325.     available to your logs by appending more l's, as in:
  326.  
  327.         ngate -i -lll
  328.  
  329.     which would set a logging level of 3. Ngate 0.20 has only one
  330.     logging level, but more detail is planned for subsequent releases.
  331.  
  332. 4.0 The History of nGate
  333.  
  334.     I read a lot of electronic mail. I get FIDO netmail, FIDO echomail,
  335.     internet email, and usenet.
  336.  
  337.     No one reader is suited to dealing with all these kinds of messages.
  338.     I have used many of the BBS readers, email mailers, and newsreaders
  339.     available under DOS, Windows, OS/2, and Unix. Although I have my
  340.     favourites, I have found it a real pain to get 10 minutes in a day
  341.     when I can look at mail and then have to load up several different
  342.     packages. Also, these specialized readers are very good at the
  343.     handling of mail and news data, but some have user interfaces that
  344.     are far and away ahead of the rest. I have yet to see a newsreader
  345.     that is as easy to use on a notebook as most of the FIDO message
  346.     readers are.
  347.  
  348.     My personal favourite OS/2 editor is FleetStreet, though a lot of
  349.     people prefer GoldEd, TimeEd, or the integrated editors within
  350.     BBS packages.
  351.  
  352.     In early 1995 I wrote MailGate to connect smtp email with Squish
  353.     and *.MSG message bases. The goal with it was to connect BBS's with
  354.     internet email, allowing BBS sysops to easily provide their users
  355.     with internet mail. OS/2's implementation of the unix program
  356.     SENDMAIL is short of some of the extended features available in
  357.     Unix versions, but it works extremely well and is quite reliable.
  358.     So, MailGate was born as a low-cost shareware program to accomplish
  359.     this task, and is now in use on many BBS's around the world.
  360.  
  361.     A plug: MailGate is available by anonymous ftp via:
  362.  
  363.         hobbes.nmsu.edu/incoming/mg111d.zip
  364.  
  365.     or by FREQ to fido:
  366.  
  367.         1:229/622, magic name MAILGATE
  368.  
  369.     Usenet was available through fidonet, but in my area it was slow
  370.     and sporadic. I had it available from my nntp server, but it was
  371.     difficult to locate software that would import it into a Squish
  372.     message base. The closest I was able to get was cthuang's excellent
  373.     SOUPER, which uploads and downloads SOUP packets from a news
  374.     server. Early parts of nGate were derived from his work - the
  375.     pre-release version used SOUP as an intermediary step.
  376.  
  377.     I was able to find a utility to import nntp messages to a squish
  378.     base, but not export them. I found some products that claimed
  379.     to be able to handle news import/export that crashed, messed up
  380.     the message bases, and were otherwise ill-behaved.
  381.  
  382.     Finally I decided to extend MailGate to include News, but on each
  383.     pass with the design, MailGate would lose its simplicity - one of
  384.     its most endearing features. So I created nGate as a separate
  385.     small program to do the job and to share conventions with Unix
  386.     news utilities. I have decided to start this off as a functioning
  387.     freeware utility to help other sysops avoid the frustration I
  388.     encountered, and to help mesh BBS's with the internet.
  389.  
  390.     On our system, we are lucky enough to have a full-time internet
  391.     connect, but our setup will work with a part time connect.
  392.  
  393.     We run Harald Kipp's excellent Changi news server on OS/2. It
  394.     connects to our internet connection's nntp server once an hour
  395.     and exchanges usenet articles. This setup allows us to connect
  396.     newsreaders, including nGate, to our own newsserver and read
  397.     or exchange news much more quickly than we could online.
  398.  
  399.     We run nGate -i once an hour, and a half hour later, we run
  400.     nGate -o. This keeps our usenet message bases right up to date
  401.     without clogging up our local FIDO net.
  402.  
  403.     We offer email and usenet to our BBS users for free as a community
  404.     service. 
  405.  
  406.     I have no idea what the future of BBS's is as more and more
  407.     people are web browsing, but I know it would be a worldwide
  408.     loss if BBS's were to disappear, along with the community
  409.     created and shared by sysops.
  410.  
  411.     So give nGate a whirl and let me know what you think. I'm at:
  412.  
  413.         1:229/622
  414.         daveh@sbase.com
  415.  
  416.     Have fun,
  417.  
  418.         Dave Hamilton
  419.