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