OS/2 Shareware BBS: 2 BBS/02-BBS.zip/ng034.zip/ngate.doc

Text File | 1997-03-20 | 16KB | 455 lines

                         nGate 0.3

               Copyright (c) Dave Hamilton 1995, 1997




                        WARNING

    This is freeware. It is not guaranteed to do anything, or
    to not do anything. Use it at your own risk.

    Future versions, as features are added, may become shareware.
    It is my hope that I can maintain a pre 1.0 version as freeware
    always, and add a post 1.0 version as shareware that will simply
    be more functional. I intend to have two versions. Have fun with
    this one.

    This release is, I hope, the last beta before 1.0.


Acknowledgements

    OS/2, Warp, and IBM's version of SENDMAIL are copyright (c) IBM Corp.
    Msgapi32.dll and Squish are copyright (c) SCI Communications, and are
    trademarks of Lanius Corporation.
    FleetStreet is copyright (c) by Michael Hohner and Harry Herrmannsdorfer.
    MailGate is copyright (c) by Dave Hamilton.

    Special thanks to Fabian Beutin for very heavy beta testing.

1.0 Changes

    0.34 Adds switch (-s) to use the short date posting
         format for those servers that choke on a GMT date.
         The default is the GMT date as specified in RFC977.

         Adds switch (-v) to supply verbose screen output
         during processing. The more v's you add, the more
         verbose the output, up to a level of 5. At Level
         3, you can watch the article text and headers
         come in.

         Adds switch (-a) to download a list of all newsgroups
         from your server. Warning! This could take a very long
         time. The results are stored in newsrc.all. You can
         cut and paste from there to your newsrc file to add
         new groups.

    0.33 We discover that some servers support both of the
         date formats we offer, but most will accept one
         and choke on the other.

         Added larger input buffers  which should increase
         download speed at higher connection rates.


    0.32 Fixes date bug that was reintroduced in 0.30

         Increased logging debugging degree. By increasing the
         number of 'l's you increase the verbosity of the log.
         The highest supported now is -lllll (5 l's) which will
         log the incoming lines of an article. Some users are
         reporting failure during the processing of articles.

    0.30 Increased line buffer size. It was crashing on headers with
         very long newsgroups: entries.

         Made date routine yet smarter.

    0.20 Made config file reader a little more intelligent, was crashing
         and in some cases linking the wrong area with newsgroup

         Changed Date on posted articles to conform with more news
         servers.

         Increased logging information

         Now rewrites newsrc file after each group is received instead
         of after entire retrieval

         Fixed buffer overrun when very long list of Newsgroups: was
         read, causing trap 05 crash

    0.10 First Beta Release


1.1    What is nGate?

    nGate (NewsGate) is a simple program that acts as an interface between
    an nntp news server and your Squish message base. It was designed as
    a companion program for MailGate, but kept apart from it so that

        1) a simple version could be distributed as freeware
        2) both MailGate and nGate could remain simple

    nGate retrieves unread news articles from an nntp server that you
    are connected to and tosses them into your Squish message base.
    nGate also scans messages from your Squish message base and
    posts them to an nntp news server.

    Once messages are in your message base, they may be read by
    you or your users. Depending upon how you have your BBS configured,
    your users may post responses or new messages in those areas.

    See section 4.0 for some history of how nGate evovled and how
    the author has it configured on a busy system.

1.2 Requirements

    You must be running OS/2 version 3.0 (Warp) or above.

    At the time  you run nGate, you must be connected to an internet
    provider service (ISP) and have access to a news server that uses the
    NNTP protocol. Finally, you must have a message base that is
    either Squish or *.MSG (Star-dot-Message).

    nGate does not create any temporary files when working; it relies
    on OS/2's virtual memory and handles one news article at a time.
    The more memory your machine has, the better for every program
    you run, but nGate will run safely in any amount of memory that
    OS/2 can run in.

1.3 Files and Directories

    nGate requires two files to run:

        newsrc
        ngate.cfg

    The newsrc file is a list of newsgroups that you are interested
    in or "subscribed to".

    The ngate.cfg file is nGate's configuration file (big surprise)
    containing basic configuration information and a list of
    newsgroups along with the message bases that are associated
    with them.

    To locate these files, nGate searches in the following order:

        1) the environment variable MAILGATE
        2) the current directory

    Please note the order. If you have a line in your config.sys
    such as:

        SET MAILGATE=C:\MG

    nGate will look in c:\mg for its files before it looks in the
    directory you are in when it runs.

    nGate can create a log file that records its actions. If you
    run it with the logging option on, it creates the log file
    called ngate.log in the same directory as its two files.

1.3 Setting Up

    If you are already using MailGate, and have the MAILGATE environment
    variable set, it is suggested you copy nGate.exe to that directory
    and create your configuration files there. If not, create a
    directory (it doesn't have to be at the root of the drive) and
    create your configs in that directory. When you run nGate, change
    to that directory.

    If you don't already have MSGAPI32.DLL on your system, copy the
    one enclosed to somewhere in your LIB path. OS2\DLL is usually
    a good place to put it.

1.4 The newsrc File

    Using a text editor, create a file called "newsrc" (without the
    quotes, no file extension). Create one line for each newsgroup
    you want, ending with a colon. Example:

        comp.os.os2.advocacy:
        comp.os.os2.bugs:

    Each time nGate runs, it will read this file, and it will UPDATE
    this file with the low and high article number pointers from the
    server. After nGate has run, your newsrc file will look something
    like this:

            comp.os.os2.advocacy: 23413-25752
            comp.os.os2.bugs: 7361-7407

    You can add a new group any time you like. It is the colon that
    causes nGate to query the server for new articles, and the existing
    numbers that let nGate and the server to know which articles you
    haven't received yet.

    Note that nGate uses a conventional newsrc file common to many
    Unix and OS/2 applications. If you are installing nGate along with
    or in place of, another news reader, you may be able to use an
    existing file. Most newsreaders we've seen use this format.

2.1 ngate.cfg

    This file is also created with a text editor. The first few lines
    describe environment information. These are followed by one line
    for every news group you subscribe to.

    Here's an example file:

        from            1:229/622.0            ; From node
        to                All                    ; To: field
        origin            "Serenity Base"        ; for in and out msgs
        domain             sbase.com            ; for outbound
        newsserver        leebeach.sbase.com    ; our news server's address

        alt.als  $L:\Max\News\7003
        alt.religion.scientology $L:\Max\News\1999
        comp.os.os2.comm   $L:\Max\News\5006
        comp.os.os2.games   $L:\Max\News\5007
        comp.os.os2.mail-news   $L:\Max\News\5008
        comp.os.os2.marketplace   $L:\Max\News\5009
        comp.os.os2.misc   $L:\Max\News\5010
        comp.os.os2.multimedia   $L:\Max\News\5011
        comp.os.os2.networking   $L:\Max\News\5012
        comp.os.os2.networking.misc   $L:\Max\News\5013

    You can probably figure out most of the config file from the
    example above, but we'll go over each of the lines just in
    case.

    Blank lines are ignored.

    A semicolon and everything to the right of it is ignored. You can
    (and are encouraged to) use semicolons to comment the lines in
    your file, or to 'comment-out' lines you with to temporarily
    turn off.

2.2 From

    This is the fido or network address of your own system. It is
    used for incoming articles to fill in the 'from' address, because
    FIDO requires such address to be present. From a working perspective
    it doesn't do anything at all, but it must be entered.

2.3 To

    As above, this field must be filled in, or some message readers
    will lose their minds. 'All' is probably the best choice here,
    given the nature of usenet.

2.4 Origin

    This field serves two purposes. On inbound mail, it takes on a
    role similar to above, and just fills in a field in the message.

    For outbound articles, it is used for the 'Organization:' field
    in articles posted from your system to usenet.

    Unless you can think of anything better, this would normally be
    the name of your BBS.

2.5 Domain

    This is the domain name of your BBS. It is used by nGate to
    generate an email address for the person posting articles
    from your system to usenet. Some message editors such as
    FleetStreet let you use a complete email address in the
    From field. Others insist on first/last names, or aliases.

    When nGate is scanning outbound messages, it looks at the
    'from' field to see if it contains an atpersand (@). If it
    does, the field is used as-is. If not, the contents of the
    field are trimmed of leading and trailing spaces, internal
    spaces are converted to dots, and it is converted to lower
    case. Then, the atpersand is appended, followed by this
    Domain name.

    For example, assume you have this configured:

        domain my-bbs.com

    Here's what nGate will do with the names of these posters:

        Finds                    Changes to
        -----                    ----------
        [e-mail]        [e-mail]
        Squeaky                    [e-mail]
        Harry Armes                [e-mail]

2.6 newsserver

    This is the tcp/ip address of the news server you will connect
    to. Example:

        rosie.sbase.com

    Note that ISP's can configure their servers so that you can have
    read-only access, read-and-post access, or no access.

    When nGate first connects with the server it will determine access
    from the server. If you don't have posting permission and you
    attempt to post articles to the server, nGate will tell you so.
    If you operate within the access you have, nGate will not report
    anything. If nGate is silent, everything's working.

2.7 newsgroup <-> message base lines

    These lines consist of a newsgroup name, one or more spaces,
    and the path to the message base associated with the newsgroup.

    If the message base is Squish, the path will begin with a
    dollar sign ($).

    If the message base is *.MSG, just provide the path.

    Example:

        comp.os.os2.comm   $L:\Max\News\5006

3.1 Running nGate

    Ok, let's assume you have your config files set up. Change to
    the directory where nGate and its config files live.

    To IMPORT articles, type:

        ngate -i

    nGate will connect to the server and process all lines you
    have entered in your newsrc file. For each line, it will locate
    your Squish or *.MSG message base, and query the server for any
    new articles. As it runs, it will display the newsgroup it is
    currently working on, the number of new articles to be downloaded,
    and its progress as it downloads them and tosses them into your
    message base. When it has downloaded all the articles, it will
    return to the OS/2 command prompt.

    To send OUTBOUND articles, type:

        ngate -o

    nGate will connect to the server and determine that you do have
    posting access. Next it will process each message base you have
    configured, scanning for newly entered messages. As it finds
    them, it will post them to the newsserver and mark them as
    SENT in your message base. nGate will display a line for each
    newsgroup it is processing, and if there are any articles to post,
    will display a count of posted articles. Depending upon your
    hardware and memory, it may take several seconds or longer to
    scan each message area.

    If you want to process INBOUND and OUTBOUND articles on the
    same pass, type:

        ngate -i -o

    nGate will process INBOUND first, then OUTBOUND.

3.2 Logging

    To turn on logging (recommended), add the -l switch to your
    command. For example, to import articles with logging, type:

        ngate -i -l

    As newer versions of nGate are released, more detail will be
    available to your logs by appending more l's, as in:

        ngate -i -lll

    which would set a logging level of 3. Ngate 0.20 has only one
    logging level, but more detail is planned for subsequent releases.

4.0 The History of nGate

    I read a lot of electronic mail. I get FIDO netmail, FIDO echomail,
    internet email, and usenet.

    No one reader is suited to dealing with all these kinds of messages.
    I have used many of the BBS readers, email mailers, and newsreaders
    available under DOS, Windows, OS/2, and Unix. Although I have my
    favourites, I have found it a real pain to get 10 minutes in a day
    when I can look at mail and then have to load up several different
    packages. Also, these specialized readers are very good at the
    handling of mail and news data, but some have user interfaces that
    are far and away ahead of the rest. I have yet to see a newsreader
    that is as easy to use on a notebook as most of the FIDO message
    readers are.

    My personal favourite OS/2 editor is FleetStreet, though a lot of
    people prefer GoldEd, TimeEd, or the integrated editors within
    BBS packages.

    In early 1995 I wrote MailGate to connect smtp email with Squish
    and *.MSG message bases. The goal with it was to connect BBS's with
    internet email, allowing BBS sysops to easily provide their users
    with internet mail. OS/2's implementation of the unix program
    SENDMAIL is short of some of the extended features available in
    Unix versions, but it works extremely well and is quite reliable.
    So, MailGate was born as a low-cost shareware program to accomplish
    this task, and is now in use on many BBS's around the world.

    A plug: MailGate is available by anonymous ftp via:

        hobbes.nmsu.edu/incoming/mg111d.zip

    or by FREQ to fido:

        1:229/622, magic name MAILGATE

    Usenet was available through fidonet, but in my area it was slow
    and sporadic. I had it available from my nntp server, but it was
    difficult to locate software that would import it into a Squish
    message base. The closest I was able to get was cthuang's excellent
    SOUPER, which uploads and downloads SOUP packets from a news
    server. Early parts of nGate were derived from his work - the
    pre-release version used SOUP as an intermediary step.

    I was able to find a utility to import nntp messages to a squish
    base, but not export them. I found some products that claimed
    to be able to handle news import/export that crashed, messed up
    the message bases, and were otherwise ill-behaved.

    Finally I decided to extend MailGate to include News, but on each
    pass with the design, MailGate would lose its simplicity - one of
    its most endearing features. So I created nGate as a separate
    small program to do the job and to share conventions with Unix
    news utilities. I have decided to start this off as a functioning
    freeware utility to help other sysops avoid the frustration I
    encountered, and to help mesh BBS's with the internet.

    On our system, we are lucky enough to have a full-time internet
    connect, but our setup will work with a part time connect.

    We run Harald Kipp's excellent Changi news server on OS/2. It
    connects to our internet connection's nntp server once an hour
    and exchanges usenet articles. This setup allows us to connect
    newsreaders, including nGate, to our own newsserver and read
    or exchange news much more quickly than we could online.

    We run nGate -i once an hour, and a half hour later, we run
    nGate -o. This keeps our usenet message bases right up to date
    without clogging up our local FIDO net.

    We offer email and usenet to our BBS users for free as a community
    service.

    I have no idea what the future of BBS's is as more and more
    people are web browsing, but I know it would be a worldwide
    loss if BBS's were to disappear, along with the community
    created and shared by sysops.

    So give nGate a whirl and let me know what you think. I'm at:

        1:229/622
        [e-mail]

    Have fun,

        Dave Hamilton