1 Citadel/UX Network Manual
2 See copyright.doc for copyright information
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.
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
18 citmail.c A patch to allow Citadel/UX users to receive
19 mail through the normal UUCP mail facility.
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.
33 There are three options in setup which must be properly set. The
34 first is NODENAME, which must be the same as your uucp system name. The second
35 is HUMANNODE, which is the "long" full name of your system (for documentation).
36 The third is FQDN, which is your system's fully qualified domain name. If
37 you don't have a domain, just set this value to your NODENAME followed by the
38 string ".UUCP" (a traditional convention, even if you're not on a UUCP net).
41 SETTING UP SYSTEMS FILES
43 For each of your neighboring Citadel/UX systems you must create a systems
44 file. The file is called network/systems/sysname, where sysname is the other
45 system's node name. The first line contains a command that transfers a spool
46 file to the network/spoolin directory on the remote system. The string "%s"
47 will be replaced by the name of the spool file by netproc. You may only use
48 %s ONCE in the command line. Usually, some sort of UUCP transfer will be used
49 to do the transfer, but you may use any facility you want, *** as long as the
50 file ends up in the network/spoolin directory on the remote system ***. In
51 a typical system, you will probably use uux to pipe the file through the
52 command "rcit -c" on the remote system. When the remote system receives this
53 command, it will copy standard input to the network/spoolin directory, and
54 then begin processing the file as soon as it is there.
55 After the command line you should enter the names of all the rooms you
56 intend to share with this system. Each room name should be followed by a
57 line containing a zero - this extra field is the "last message sent" (which
58 will be updated by netproc when it is run). Here is a sample systems file for
59 a node called uncnsrd:
61 cat %s |uux - uncnsrd!rcit -c
69 The rooms "Network Test", "Gateway", and "The Room" will be spooled to
70 the remote system. These rooms should be designated as network rooms with
71 the .<A>ide <E>ditRoom command.
76 Calling netproc with no arguments simply looks in the network/spoolin
77 directory for newly arrived messages, and posts them if it finds any.
78 To batch new messages and send them off to a remote system, the usage
82 will do outbound network processing for system "sysname". It is recommended
83 that you use the cron program to handle your network processing on a routine
84 basis automatically. Arrange with your netneighbors for both of your systems
85 to batch new messages before actual polls take place, to guarantee that
86 messages travel across the network as quickly as possible.
89 NETWORKING WITH A USENET NEWS SITE
91 Two filters are provided that will allow a room to be equivalent to a
92 UseNet newsgroup. rcit, when called without the -c argument, will assume
93 that standard input is in the news format, and convert it before processing.
94 Likewise, the filter cux2ascii.c converts Citadel format to news format,
95 allowing you to use command lines such as
97 cat %s |cux2ascii |uux - uunet!rnews
99 ...the remote system need not be a Citadel/UX. By default, room names are
100 the same as the newsgroup names. However, if you wish the room name to be
101 different, you may specify so in the network/rnews.xref file. Here is a
104 comp.unix.wizards,UNIX wizards
105 alt.drugs,Drugs and Narcotics
108 It is rather simple, each line taking the form of newsgroupname,sysname.
109 There may not be any spaces in the newsgroup name, but there may be spaces
110 in the corresponding room name.
113 USING CITADEL/UX AS YOUR LOCAL E-MAIL SYSTEM
115 To use Citadel/UX as your local mail system, simply define the "citmail"
116 program as your *local* mail delivery agent. You can plug citmail into any
117 popular mail routing system, including sendmail, smail, MMDF, etc.
119 Once you are using citmail as your local mail delivery agent, all users
120 on your BBS may receive mail. They can use addresses like
121 "my_user_name@yoursite.com" (note the spaces in the user's name are replaced
122 by underscores) or "cit1234@yoursite.com" (where 1234 is the user's user
125 Messages may be posted by mail if you have this program installed. Simply
126 use the prefix "room_" -- for example, a message addressed to
127 "room_hot_pink_amoebas@uncnsrd.mt-kisco.ny.us would be posted in the room "Hot
128 Pink Amoebas" at the target system.
130 PLEASE NOTE that for your BBS users to be able to send mail, you should
131 check the mailer command at the top of "netmailer.c" to be sure that it is
132 the correct mailer command for your system. You might need a command like
133 "sendmail %s" for SMTP or "rmail %s" for UUCP.
138 The file network/mail.aliases is a simple list of aliases for the various
139 mailers to use. Each line takes the form
143 Obviously, neither the alias nor the name can contain commas. The name
144 may also be the system name "sysop", where messages sent to sysop will
145 be posted in the Aide> room.
148 CITADEL/UX NETWORK MAIL
150 Citadel/UX has the ability to transport mail in a simple and
151 transparent fashion not unlike the way public messages are sent. Users may
152 enter recipient names exactly as they appear on top of messages (i.e.,
153 user name @ system name). In addition, mail routing is provided, allowing
154 users to send mail to systems which do not directly connect with their own.
156 When entering a message in the Mail> room, a user may type a recipient
157 name on the local system, or on a remote system. If the recipient is not
158 local, citadel.c calls netmailer.c, which is a standalone program that handles
159 network mail. This runs in a multithreaded mode, allowing netmailer to run in
160 the background while the user goes on to do something else.
163 INTELLIGENT NETWORK PROCESSING AND THE MAIL.SYSINFO FILE
165 There is (or soon will be) a file in your network directory called
166 "mail.sysinfo". In earlier releases of the network software, the system
167 administrator had to manually configure this file. Starting with netproc
168 version 2.1, the system should now create and configure the file automatically.
169 Note that all information may not appear in the file immediately. When a
170 message arrives from a system on the network, your system will attempt to
171 add that system to its network map. If the originating system is one of your
172 netneighbors, it will look for a systems file in the network/systems directory
173 to determine whether it is a valid neighbor. If the originating system is
174 not a neighbor, but the message arrived via a valid neighbor, your map will
175 be updated accordingly, with an entry for the new system showing the next hop
178 So, under normal circumstances you shouldn't have to configure this file at
179 all. But if you need to do something special, or if for some reason netproc
180 detects the topology wrong, here's how to configure mail.sysinfo. There
181 are three types of entries in this file. A "use" entry tells the system which
182 neighbor to route a message through to get to a particular non-neighboring
183 system. A "bin" entry tells the system that a particular neighbor supports
184 net mail. If there are systems that either do not have the netmailer or are
185 not running Citadel/UX, but can be reached by regular electronic mail, you
186 can use the "uum" command. Type "uum" followed by an address (for the user
187 name, use a %s which will be replaced by the user name at the remote
188 system. Here is a sample network map, where our system is called "myself"
189 and all systems have Citadel/UX EXCEPT for "gateway" and "mailsys":
191 gateway---mailsys _____testbbs
193 othersys ----- myself ----- thebox
197 In this example, our neighbors are "othersys" and "thebox". othersys
198 also connects to funboard, and thebox connects to testbbs and theirsys. If
199 everyone supports netmail, the network/mail.sysinfo file would look like this:
217 uum othersys!gateway!%s
220 uum othersys!gateway!mailsys!%s
222 (Keep in mind that your file will contain additional system-generated
225 The "bin" entries specify neighbors, the "use" entries specify routing, and
226 the "uum" entries specify regular UUCP mail. The method of delivery is totally
227 transparent to the user, who only needs to enter the recipient as user@sysname.
228 Note that netproc will probably stuff lots of other info into each entry.
233 Tired of idiots lowering the quality of the net? You can set up a "kill
234 file" in ./network/filterlist that can be used to filter out messages from
235 any user, room, or system (or any combination). The three fields should be
236 separated by commas, and the name "*" may be used as a wildcard in any field.
239 # Filter out user "The Idiot" in "Idiot Room" at "idiotbbs"
241 The Idiot,Idiot Room,idiotbbs
243 # Filter out the same user, but in every room
247 # Filter out all messages from a system we don't like
251 # Filter out messages in a certain room from a certain system
255 You could also put a "*" wildcard in all three fields, essentially
256 disabling all incoming messages. Obviously you don't want to do this.
261 That should cover everything you need to get running. By the way, gateway
262 software for StoneHenge and NYTI FordBoard systems is available upon special
263 request. And, a Cit86Net gateway is now available. For the latest version
264 of this program, or to leave comments/suggestions, call my board -
265 UNCENSORED! BBS at (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).