citadel/docs/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  This has changed markedly in the last few versions.  Citadel used to require
 106 extensive patching into your system's MTA.  Now it is a fully functional
 107 standalone e-mail system, complete with its own SMTP, POP3, and IMAP4
 108 implementations.  Please refer to "inetmailsetup.txt" for more information.
 109
 110
 111   MAIL ALIASES
 112
 113    The file network/mail.aliases is a simple list of aliases for the various
 114 mailers to use. Each line takes the form
 115
 116 alias,name
 117
 118    Obviously, neither the alias nor the name can contain commas. The name
 119 may also be the system name "sysop", where messages sent to sysop will
 120 be posted in the Aide> room.
 121
 122
 123   CITADEL/UX NETWORK MAIL
 124
 125    Citadel/UX has the ability to transport mail in a simple and
 126 transparent fashion not unlike the way public messages are sent. Users may
 127 enter recipient names exactly as they appear on top of messages (i.e.,
 128 user name @ system name). In addition, mail routing is provided, allowing
 129 users to send mail to systems which do not directly connect with their own.
 130
 131   When entering a message in the Mail> room, a user may type a recipient
 132 name on the local system, or on a remote system. If the recipient is not
 133 local, citadel.c calls netmailer.c, which is a standalone program that handles
 134 network mail.  This runs in a multithreaded mode, allowing netmailer to run in
 135 the background while the user goes on to do something else.
 136
 137
 138   INTELLIGENT NETWORK PROCESSING AND THE MAIL.SYSINFO FILE
 139
 140   There is (or soon will be) a file in your network directory called
 141 "mail.sysinfo".  In earlier releases of the network software, the system
 142 administrator had to manually configure this file.  Starting with netproc
 143 version 2.1, the system should now create and configure the file automatically.
 144 Note that all information may not appear in the file immediately.  When a
 145 message arrives from a system on the network, your system will attempt to
 146 add that system to its network map.  If the originating system is one of your
 147 netneighbors, it will look for a systems file in the network/systems directory
 148 to determine whether it is a valid neighbor.  If the originating system is
 149 not a neighbor, but the message arrived via a valid neighbor, your map will
 150 be updated accordingly, with an entry for the new system showing the next hop
 151 to get there.
 152
 153   So, under normal circumstances you shouldn't have to configure this file at
 154 all.  But if you need to do something special, or if for some reason netproc
 155 detects the topology wrong, here's how to configure mail.sysinfo.  There
 156 are three types of entries in this file. A "use" entry tells the system which
 157 neighbor to route a message through to get to a particular non-neighboring
 158 system. A "bin" entry tells the system that a particular neighbor supports
 159 net mail. If there are systems that either do not have the netmailer or are
 160 not running Citadel/UX, but can be reached by regular electronic mail, you
 161 can use the "uum" command. Type "uum" followed by an address (for the user
 162 name, use a %s which will be replaced by the user name at the remote
 163 system. Here is a sample network map, where our system is called "myself"
 164 and all systems have Citadel/UX EXCEPT for "gateway" and "mailsys":
 165
 166                 gateway---mailsys          _____testbbs
 167                 /                         /
 168            othersys ----- myself ----- thebox
 169               /                          \_______theirsys
 170           funboard
 171
 172    In this example, our neighbors are "othersys" and "thebox". othersys
 173 also connects to funboard, and thebox connects to testbbs and theirsys. If
 174 everyone supports netmail, the network/mail.sysinfo file would look like this:
 175
 176 funboard
 177 use othersys
 178
 179 testbbs
 180 use thebox
 181
 182 theirsys
 183 use thebox
 184
 185 othersys
 186 bin Mail
 187
 188 theirsys
 189 bin Mail
 190
 191 gateway
 192 uum othersys!gateway!%s
 193
 194 mailsys
 195 uum othersys!gateway!mailsys!%s
 196
 197   (Keep in mind that your file will contain additional system-generated
 198 information.)
 199
 200   The "bin" entries specify neighbors, the "use" entries specify routing, and
 201 the "uum" entries specify Internet mail. The method of delivery is totally
 202 transparent to the user, who only needs to enter the recipient as user@sysname.
 203 Note that netproc will probably stuff lots of other info into each entry.
 204
 205
 206   THE KILL FILE
 207
 208    Tired of idiots lowering the quality of the net?  You can set up a "kill
 209 file" in ./network/filterlist that can be used to filter out messages from
 210 any user, room, or system (or any combination).  The three fields should be
 211 separated by commas, and the name "*" may be used as a wildcard in any field.
 212 Examples:
 213
 214  # Filter out user "The Idiot" in "Idiot Room" at "idiotbbs"
 215  #
 216  The Idiot,Idiot Room,idiotbbs
 217
 218  # Filter out the same user, but in every room
 219  #
 220  The Idiot,*,idiotbbs
 221
 222  # Filter out all messages from a system we don't like
 223  #
 224  *,*,idiotbbs
 225
 226  # Filter out messages in a certain room from a certain system
 227  #
 228  *,The Room,idiotbbs
 229
 230    You could also put a "*" wildcard in all three fields, essentially
 231 disabling all incoming messages.  Obviously you don't want to do this.
 232
 233
 234   CONCLUSION
 235
 236    That should cover everything you need to get running. By the way, gateway
 237 software for StoneHenge and NYTI FordBoard systems is available upon special
 238 request.  And, a Cit86Net gateway is now available.  For the latest version
 239 of this program, or to leave comments/suggestions, visit UNCENSORED! BBS at
 240 uncensored.citadel.org.