citadel/network.txt

   1                           Citadel/UX Network Manual
   2                  See copyright.doc for copyright information
   3
   4
   5   OVERVIEW
   6
   7    The fundamental structure of the networker is fairly simple, however, it
   8 has enough features to make it a bit complicated. This is probably the most
   9 difficult part of the entire Citadel/UX package. So before we dive in head
  10 first, let's look at the various network files and directories.
  11
  12  netproc.c                    Does all of the actual network processing.
  13  rcit.c                       Feeds standard input into the networker, also
  14                               has the ability to translate UseNet news format
  15                               into Citadel/UX binary format.
  16  netmailer.c                  Called by the main program when a user sends a
  17                               network mail message.
  18  citmail.c                    A local MDA which can allow Citadel users to
  19                               receive Internet mail.
  20  cux2ascii.c                  A filter which translates Citadel/UX binary
  21                               format to UseNet news format.
  22  network                      Directory in which all network files reside.
  23  network/systems              Contains network info for each neighboring system
  24  network/systems/sysname      Network file for a node called "sysname".
  25  network/mail.aliases         Aliases for the mailer.
  26  network/rnews.xref           Cross-references room names to newsgroup names.
  27  network/mail.sysinfo         Contains routing information for network mail.
  28  network/filterlist           The "kill file" for your system.
  29
  30
  31   SETUP
  32
  33   There are a few options in the Global System Configuration which pertain
  34 to the network.  They are:
  35
  36  -> node name: this is the unqualified "short" node name which uniquely
  37 identifies your system on a Citadel network.
  38  -> fully-qualified domain name (FQDN): this identifies how your computer is
  39 named on the Internet.
  40  -> Human-readable node name: this is a longer, more verbose name for your
  41 system.  It is also used as your "node title" on older Cit86Net-based
  42 networks.
  43
  44
  45    SETTING UP SYSTEMS FILES
  46
  47    Please note that it is *much* easier to use the "netsetup" (command-line)
  48 or "dnetsetup" (curses-based) utilities to create systems files.  You should
  49 only work with these files manually if you need to do something special.
  50
  51    For each of your neighboring Citadel/UX systems you must create a systems
  52 file. The file is called network/systems/sysname, where sysname is the other
  53 system's node name. The first line contains a command that transfers a spool
  54 file to the network/spoolin directory on the remote system. The string "%s"
  55 will be replaced by the name of the spool file by netproc. You may only use
  56 %s ONCE in the command line. Usually, some sort of remote copy will be used
  57 to do the transfer, but you may use any facility you want, *** as long as the
  58 file ends up in the network/spoolin directory on the remote system ***.
  59
  60    If you're on the Internet, or any TCP/IP network, your systems file should
  61 contain the following copy command:
  62
  63 cat %s >>./network/spoolout/remote_system_name
  64
  65    This simply stores the outbound spool data in a file in the "spoolout"
  66 directory, where it will be picked up by server-to-server transfer programs.
  67
  68    After the command line you should enter the names of all the rooms you
  69 intend to share with this system. Each room name should be followed by a
  70 line containing a zero - this extra field is the "last message sent" (which
  71 will be updated by netproc when it is run). Here is a sample systems file for
  72 a node called uncnsrd:
  73
  74 cat %s >>./network/spoolout/uncnsrd
  75 Network Test
  76 0
  77 Gateway
  78 0
  79 The Room
  80 0
  81
  82   The rooms "Network Test", "Gateway", and "The Room" will be spooled to
  83 the remote system. These rooms should be designated as network rooms with
  84 the .<A>ide <E>ditRoom command.
  85
  86
  87   USING NETPROC
  88
  89
  90    Calling netproc with no arguments causes it to look in the network/spoolin
  91 directory for newly arrived messages, and posts them if it finds any.  It then
  92 automatically batches up new messages on your system to be sent to your net
  93 neighbors, and exports those messages to them.  It is recommended
  94 that you use the cron program to handle your network processing on a routine
  95 basis automatically.  Arrange with your netneighbors for both of your systems
  96 to batch new messages before actual polls take place, to guarantee that
  97 messages travel across the network as quickly as possible.
  98
  99    Calling netproc with the -i flag causes it to skip the export phase, and
 100 handle incoming messages only.
 101
 102
 103   USING CITADEL/UX AS YOUR LOCAL E-MAIL SYSTEM
 104
 105    To use Citadel/UX as your local mail system, simply define the "citmail"
 106 program as your *local* mail delivery agent.  You can plug citmail into any
 107 popular mail routing system, including sendmail, smail, MMDF, etc.
 108
 109    Once you are using citmail as your local mail delivery agent, all users
 110 on your BBS may receive mail.  They can use addresses like
 111 "my_user_name@yoursite.com" (note the spaces in the user's name are replaced
 112 by underscores) or "cit1234@yoursite.com" (where 1234 is the user's user
 113 number).
 114
 115    Messages may be posted by mail if you have this program installed.  Simply
 116 use the prefix "room_" -- for example, a message addressed to
 117 "room_hot_pink_amoebas@uncnsrd.mt-kisco.ny.us would be posted in the room "Hot
 118 Pink Amoebas" at the target system.
 119
 120    PLEASE NOTE that for your BBS users to be able to send mail, you should
 121 check the mailer command at the top of "netmailer.c" to be sure that it is
 122 the correct mailer command for your system.  You might need a command like
 123 "sendmail %s" or "smail %s" depending on what MTA you're using.
 124
 125
 126   MAIL ALIASES
 127
 128    The file network/mail.aliases is a simple list of aliases for the various
 129 mailers to use. Each line takes the form
 130
 131 alias,name
 132
 133    Obviously, neither the alias nor the name can contain commas. The name
 134 may also be the system name "sysop", where messages sent to sysop will
 135 be posted in the Aide> room.
 136
 137
 138   CITADEL/UX NETWORK MAIL
 139
 140    Citadel/UX has the ability to transport mail in a simple and
 141 transparent fashion not unlike the way public messages are sent. Users may
 142 enter recipient names exactly as they appear on top of messages (i.e.,
 143 user name @ system name). In addition, mail routing is provided, allowing
 144 users to send mail to systems which do not directly connect with their own.
 145
 146   When entering a message in the Mail> room, a user may type a recipient
 147 name on the local system, or on a remote system. If the recipient is not
 148 local, citadel.c calls netmailer.c, which is a standalone program that handles
 149 network mail.  This runs in a multithreaded mode, allowing netmailer to run in
 150 the background while the user goes on to do something else.
 151
 152
 153   INTELLIGENT NETWORK PROCESSING AND THE MAIL.SYSINFO FILE
 154
 155   There is (or soon will be) a file in your network directory called
 156 "mail.sysinfo".  In earlier releases of the network software, the system
 157 administrator had to manually configure this file.  Starting with netproc
 158 version 2.1, the system should now create and configure the file automatically.
 159 Note that all information may not appear in the file immediately.  When a
 160 message arrives from a system on the network, your system will attempt to
 161 add that system to its network map.  If the originating system is one of your
 162 netneighbors, it will look for a systems file in the network/systems directory
 163 to determine whether it is a valid neighbor.  If the originating system is
 164 not a neighbor, but the message arrived via a valid neighbor, your map will
 165 be updated accordingly, with an entry for the new system showing the next hop
 166 to get there.
 167
 168   So, under normal circumstances you shouldn't have to configure this file at
 169 all.  But if you need to do something special, or if for some reason netproc
 170 detects the topology wrong, here's how to configure mail.sysinfo.  There
 171 are three types of entries in this file. A "use" entry tells the system which
 172 neighbor to route a message through to get to a particular non-neighboring
 173 system. A "bin" entry tells the system that a particular neighbor supports
 174 net mail. If there are systems that either do not have the netmailer or are
 175 not running Citadel/UX, but can be reached by regular electronic mail, you
 176 can use the "uum" command. Type "uum" followed by an address (for the user
 177 name, use a %s which will be replaced by the user name at the remote
 178 system. Here is a sample network map, where our system is called "myself"
 179 and all systems have Citadel/UX EXCEPT for "gateway" and "mailsys":
 180
 181                 gateway---mailsys          _____testbbs
 182                 /                         /
 183            othersys ----- myself ----- thebox
 184               /                          \_______theirsys
 185           funboard
 186
 187    In this example, our neighbors are "othersys" and "thebox". othersys
 188 also connects to funboard, and thebox connects to testbbs and theirsys. If
 189 everyone supports netmail, the network/mail.sysinfo file would look like this:
 190
 191 funboard
 192 use othersys
 193
 194 testbbs
 195 use thebox
 196
 197 theirsys
 198 use thebox
 199
 200 othersys
 201 bin Mail
 202
 203 theirsys
 204 bin Mail
 205
 206 gateway
 207 uum othersys!gateway!%s
 208
 209 mailsys
 210 uum othersys!gateway!mailsys!%s
 211
 212   (Keep in mind that your file will contain additional system-generated
 213 information.)
 214
 215   The "bin" entries specify neighbors, the "use" entries specify routing, and
 216 the "uum" entries specify Internet mail. The method of delivery is totally
 217 transparent to the user, who only needs to enter the recipient as user@sysname.
 218 Note that netproc will probably stuff lots of other info into each entry.
 219
 220
 221   THE KILL FILE
 222
 223    Tired of idiots lowering the quality of the net?  You can set up a "kill
 224 file" in ./network/filterlist that can be used to filter out messages from
 225 any user, room, or system (or any combination).  The three fields should be
 226 separated by commas, and the name "*" may be used as a wildcard in any field.
 227 Examples:
 228
 229  # Filter out user "The Idiot" in "Idiot Room" at "idiotbbs"
 230  #
 231  The Idiot,Idiot Room,idiotbbs
 232
 233  # Filter out the same user, but in every room
 234  #
 235  The Idiot,*,idiotbbs
 236
 237  # Filter out all messages from a system we don't like
 238  #
 239  *,*,idiotbbs
 240
 241  # Filter out messages in a certain room from a certain system
 242  #
 243  *,The Room,idiotbbs
 244
 245    You could also put a "*" wildcard in all three fields, essentially
 246 disabling all incoming messages.  Obviously you don't want to do this.
 247
 248
 249   CONCLUSION
 250
 251    That should cover everything you need to get running. By the way, gateway
 252 software for StoneHenge and NYTI FordBoard systems is available upon special
 253 request.  And, a Cit86Net gateway is now available.  For the latest version
 254 of this program, or to leave comments/suggestions, call my board  -
 255 UNCENSORED! BBS at (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).