Document: nodelist.txt
Revision: 001
Date:     2002-11-01

                  Human-readable (HR) distribution nodelist
                            November 1, 2002
                             andrew clarke
                          3:633/285.4{at}fidonet
                           mail{at}ozzmosis.com


Status of this document
-----------------------

  This document is a FidoNet Standards Proposal (FSP).

  This document specifies an optional FidoNet standard protocol for
  the FidoNet community, and requests discussion and suggestions for
  improvements.

  This document is released to the public domain, and may be used,
  copied or modified for any purpose whatever.


Rationale
---------

With the advent of Internet-capable FidoNet nodes, the FTS-0005 nodelist
format has now been rendered woefully inadequate to describe all the
mail-delivery capabilities of each node.  This document aims to describe
an attempt to design a new nodelist format to rectify this situation
with the aim of being able to translate back to FTS-5 format without
difficulty.


Human-readable (HR) nodelist format
-----------------------------------

For simplicity and ease of use a human-readable (HR) ASCII text file
format was chosen (in preference to, for example, CSV [Comma Separated
Values] or XML [eXtensible Markup Language] formats).  Of course this
does not rule out the use of (or conversion to) these formats for future
distribution of the FidoNet nodelist or segments thereof.


Lines
-----

Lines in the HR nodelist are separated by a single newline character
(ASCII 10).  Blank (empty) lines are permitted.


Comments
--------

All comments in the HR nodelist must begin with either a semicolon (;)
or hash/hatch (#) characters in the first column of a line of text.  The
nodelist comment ends at the first newline character.


Keywords
--------

Keywords in the HR nodelist must begin in the first column of a line of
text.  If a keyword has a [data] portion, a space (ASCII 32) should be
placed between the keyword and the data.  Keywords are case neutral, ie.
they may be all uppercase, all lowercase, or a mixture of the two.

The following keywords are proposed:

  Domain [domain]

      Defines the FTN domain, [domain], that the nodelist applies
      to.  This should be specified before any of the keywords below.

  Address [address]

      The [address] (in zone:net/node format) following the Address
      keyword defines the address of a node in the nodelist.  Point
      addresses are not permitted.  Each time an Address line appears in
      the HR nodelist, the information that follows it applies to that
      node only.  Multiple Address keywords for the same node are
      permitted to describe nodes with multiple mail delivery methods
      with differing online times (refer to the Online keyword below).

  Status [type]

      The Status keyword defines the status "type" of a node.  If no
      Status keyword is present the node is a normal node entry.  The
      following status types may be used:

          Zone

              Defines a geographic zone and its coordinator.

          Region

              Defines a geographic region and its coordinator.

          Host

              Defines a local network and its host.

          Net

              The "Net" type is a synonym for "Host".

          Hub

              Defines of a routing sub-unit within a multilevel local
              network.  The hub is the routing focal point for its
              child nodes.

          Private

              Defines a private node.

          Pvt

              The "Pvt" type is a synonym for "Private".

          Hold

              Defines a node which is temporarily down.  Mail may be
              sent to its parent node and held there.

          Down

              Defines a node which is inoperational.  Mail may not be
              sent to it.  This keyword may not be used for longer than
              two weeks on any single node, at which point the "down"
              node is to be removed from the nodelist.

  Parent [address]

      The [address] (in zone:net/node format) following the Parent
      keyword defines the parent (or uplink) of a node.   For Zone
      listings, no Parent keyword is allowed.  For all other purposes it
      is mandatory.  

  Uplink

      The "Uplink" keyword is a synonym for "Parent".

  Name [text]

      The [text] following the Name keyword contains the name by which a
      node is commonly known.  This text may contain any alphanumeric or
      punctuation characters other than commas or underscores.

  Location [text]

      The [text] following the Location keyword contains the
      geographical location of a node.  It is usually expressed as the
      primary local location (town, suburb, city, etc.) plus the
      identifier of the regional geopolitical administrative district
      (state, province, department, county, etc.).  Wherever possible,
      standard postal abbreviations for the major regional district
      should be used (IL, BC, NSW, etc.).  This text may contain any
      alphanumeric or punctuation characters other than commas or
      underscores.

  Operator [text]

      The [text] following the Operator keyword contains the name of
      the primary system operator of the node.

  SysOp [text]

      The "SysOp" keyword is a synonym for "Operator".

  Operating [text]

      The [text] following the Operating keyword describes the transport
      method, protocol and any other information required to contact the
      node using that delivery method and protocol.  Multiple Operating
      keywords for the same node are permitted to allow more than one
      delivery method to be described.

      For nodes contactable via dialup modem, the following format is
      used:

      Operating [Dialup] [FTS-1] [at] [phonenumber][,flags]

          Where [Dialup] is "Dialup" or "Dial-up", case neutral.

          Where [FTS-1] is "FTS-1" or "FTS1", case neutral.

          Where [at] is the word "at", and is case neutral and
          superfluous.

          Where [phonenumber] is in the format described by FTS-0005
          (or a superseding document).

          Where [,flags] is a comma-separated list of nodelist flags
          in the format described by FTS-0005 (or a superseding
          document).

      For nodes contactable via TCP/IP using the Binkp protocol,
      the following format is used:

      Operating [TCP/IP] [Binkp] [at] [host]

          Where [TCP/IP] is "TCP/IP" or "TCPIP" or
"TCP" or "IP",
          case neutral.

          Where [Binkp] is "Binkp", case neutral.

          Where [at] is the word "at", and is case neutral and
          superfluous.

          Where [host] specifies the fully-qualified hostname or IP
          address of the node.

  Online [text]

    The [text] following the optional Online keyword lists the times
    that the node is online.  The format of the [text] field is:
    
        [day] [start time]-[end time]

    Where [day] specifies the day of the week when the node is online,
    and is a three letter English abbreviation for the day of the week,
    ie. Sun, Mon, Tue, Wed, Thu, Fri or Sat.  [day] is case neutral.

    Where [start time] specifies the time when a node begins operation.

    Where [end time] specifies the time when a node ends operation.

    Times must be specified in 24-hour HH:MM format in UTC, where HH is
    the hours elapsed since midnight and MM is the minutes elapsed in
    that hour.  The hour and minute are to be expressed in decimal and
    must have a leading zero if their values are less than 10.

    Multiple Online keywords for the same node are permitted to allow
    multiple online times to be described.

  Contact [text]

    The [text] following the optional Contact keyword describes a method
    of contacting the operator of the node.  Multiple Contact keywords
    for the same node are permitted to allow more than one contact
    method to be described for a node.  Examples of Contact entries in
    the HR nodelist might be:

       Contact E-mail mail{at}ozzmosis.com
       Contact Fax +61-3-1234-5678


References
----------

  [FTS-0001] "A Basic FidoNet(r) Technical Standard", Randy Bush. 
  September 1995.

  [FTS-0005] "The Distribution Nodelist", Ben Baker, Rick Moore,
  David Nugent.  February 1996.

  [FSP-1011] "Binkp - a protocol for transferring FidoNet mail over
  reliable connections", Dima Maloff, Nick Soveiko, Maxim Masiutin.
  July 2000.

--- Msged/NT 6.1.1