write any new documentation, so what's there now is kind of sparse.
$Log$
+ Revision 580.85 2001/12/02 23:27:01 ajc
+ * Removed references to the old networker from the documentation. Did not
+ write any new documentation, so what's there now is kind of sparse.
+
Revision 580.84 2001/12/02 02:42:55 ajc
* Implemented new room flag QR2_SYSTEM which supresses the room from all
room listings, even for Aides (but it's still gotoable). This will be used
Fri Jul 10 1998 Art Cancro <ajc@uncensored.citadel.org>
* Initial CVS import
-
-----------------------
- Citadel/UX version 5.80
+ Citadel/UX version 5.90
-----------------------
Copyright (c) 1987-2001 by the Citadel development team.
-
-
-
Citadel/UX Internet E-mail setup instructions (mx version)
This document explains how to set up your citadel as an Internet e-mail
capable system using your current MTA (eg, sendmail, qmail, etc) as
opposed to using the Citadel/UX built-in servers.
+
Once you are through with this document you should be able to have your
users send mail from, and receive mail to
username@bbs.bbsname.citadel.org. This version of the mailsetup document
Mail sent from the BBS to an internet e-mail address should go out
immediately. E-mail coming IN to a bbs user will not process until your
-next netproc session. On my site I had to set up a relay for
+next network session. On my site I had to set up a relay for
bbs.pixel.citadel.org. In later versions of sendmail relaying is turned
off by default. Check sendmail.cf for the following line:
- "WebCit", a gateway program to allow full access to Citadel/UX BBS's
via the World Wide Web. Interactive access through any Web browser.
+
+ - Access to Citadel via *any* standards-compliant e-mail program, thanks
+ to Citadel's built-in SMTP, POP, and IMAP services.
COMING SOON:
+++ /dev/null
- BIDIRECTIONAL MAILING LIST GATEWAY INSTRUCTIONS
-
- Citadel/UX now has the ability to host a room on the BBS as a
-bidirectional gateway to an Internet mailing list. This makes it convenient
-for the entire BBS community to have reading and posting access to a mailing
-list without each member having to subscribe to the list. This document
-describes the procedure for setting up such functionality.
-
- Here's the prerequisite: you must be using Citadel as your system's local
-mail delivery agent. Please refer to network.doc for information on how to
-do this. Before attempting a mailing list, make sure that you can send and
-receive regular Internet e-mail from your Citadel system.
-
- As you may or may not know, once Citadel is your e-mail system, each room
-on the system has an e-mail address that may be used to post to the room
-from anywhere on the Internet. That address is of the form
-"room_roomname@yourhost.dom", where "roomname" is the name of the room
-(spaces replaced by underscores) and "yourhost.dom" is your fully-qualified
-domain name.
-
- The first step is to create a room for the list and then subscribe that
-room to the list. The procedure for subscribing to a list depends on what
-type of software the list server is running, and is beyond the scope of this
-document. For the purpose of example, let us suppose that you wish to
-subscribe to the "Broccoli Advocates" mailing list, and you've discovered
-that the list administrator is at broccoli-request@stalks.com and messages
-to be posted to the list should be mailed to broccoli@stalks.com. Let us
-further suppose that your BBS is at mybbs.org.
-
- So you create a room called "Broccoli Advocates". Then, because you're a
-conscientous system administrator, you give the room an Info file which
-warns users that all messages posted to the room will be posted to the list.
-
- You then send e-mail to the list administrator at
-broccoli-request@stalks.com requesting that the address
-"room_broccoli_advocates@mybbs.org" be added to the list. Once the
-administrator sets this up, the receiving end of the list is set up. Note
-that if a receive-only setup is all you want, you can stop here and you're
-done.
-
- Now you have to set things up for sending. The first thing you have to
-do is set up the file "mailinglists" which resides in the "network"
-subdirectory, which holds a table of list addresses associated with each
-room. Each line is of the form
-
- list-address,Room Name
-
- ...one room per line. You'll use this same file to set up all mailing list
-references. So for our example, the line
-
- broccoli@stalks.com,Broccoli Advocates
-
- should be added. In other words, messages originating from the "Broccoli
-Advocates" room will be mailed to broccoli@stalks.com.
-
- The next thing to do is create a file in the "network/systems" subdirectory
-which spools out new messages. Create a file "network/systems/mailinglists"
-which looks like this:
-
- mailinglist <%s
- Broccoli Advocates
- 0
-
- Note that one systems entry may be used for all mailing lists to which you
-subscribe. Just keep adding any rooms (refer to network.doc for the
-procedure) that are mapped to mailing lists.
-
- Now you're done! Just do a "netproc mailinglists" or "netproc all" on a
-regular basis (probably using cron or a similar scheduling utility) to batch
-up new messages and send them out on a regular basis.
-
-
- NOTES ABOUT MAILING LISTS:
-
- Since many listservers will only accept postings from e-mail addresses
-which are subscribed to the list, the mailing list gateway software sets the
-sending address of each message to the address of the room. The "full name"
-portion of the address will remain intact. So the posted messages will have
-headers which look like this:
-
- From: room_broccoli_advocates@mybbs.org (Joe User)
- To: broccoli@stalks.org
-
- This ensures that messages are properly posted, but it makes it difficult
-for other members of the list to learn the correct e-mail addresses of the
-users on your system. However, since there's so much spam around these
-days, that's probably just as well anyway.
-
- To prevent loops, the mailing list gateway software only spools out
-messages which originated on _your_ system. This implies that it is not
-possible to carry a gatewayed room on any type of Citadel network.
-
-
- Well, that's just about it. If you have any comments, suggestions, or
-questions, please visit UNCENSORED! BBS, either on the Internet at
-uncnsrd.mt-kisco.ny.us or via dialup at 914-244-3252.
+++ /dev/null
- Citadel/UX Network Manual
- See copyright.doc for copyright information
-
-
- OVERVIEW
-
- The fundamental structure of the networker is fairly simple, however, it
-has enough features to make it a bit complicated. This is probably the most
-difficult part of the entire Citadel/UX package. So before we dive in head
-first, let's look at the various network files and directories.
-
- netproc.c Does all of the actual network processing.
- rcit.c Feeds standard input into the networker, also
- has the ability to translate UseNet news format
- into Citadel/UX binary format.
- netmailer.c Called by the main program when a user sends a
- network mail message.
- citmail.c A local MDA which can allow Citadel users to
- receive Internet mail.
- cux2ascii.c A filter which translates Citadel/UX binary
- format to UseNet news format.
- network Directory in which all network files reside.
- network/systems Contains network info for each neighboring system
- network/systems/sysname Network file for a node called "sysname".
- network/mail.aliases Aliases for the mailer.
- network/rnews.xref Cross-references room names to newsgroup names.
- network/mail.sysinfo Contains routing information for network mail.
- network/filterlist The "kill file" for your system.
-
-
- SETUP
-
- There are a few options in the Global System Configuration which pertain
-to the network. They are:
-
- -> node name: this is the unqualified "short" node name which uniquely
-identifies your system on a Citadel network.
- -> fully-qualified domain name (FQDN): this identifies how your computer is
-named on the Internet.
- -> Human-readable node name: this is a longer, more verbose name for your
-system. It is also used as your "node title" on older Cit86Net-based
-networks.
-
-
- SETTING UP SYSTEMS FILES
-
- Please note that it is *much* easier to use the "netsetup" (command-line)
-or "dnetsetup" (curses-based) utilities to create systems files. You should
-only work with these files manually if you need to do something special.
-
- For each of your neighboring Citadel/UX systems you must create a systems
-file. The file is called network/systems/sysname, where sysname is the other
-system's node name. The first line contains a command that transfers a spool
-file to the network/spoolin directory on the remote system. The string "%s"
-will be replaced by the name of the spool file by netproc. You may only use
-%s ONCE in the command line. Usually, some sort of remote copy will be used
-to do the transfer, but you may use any facility you want, *** as long as the
-file ends up in the network/spoolin directory on the remote system ***.
-
- If you're on the Internet, or any TCP/IP network, your systems file should
-contain the following copy command:
-
-cat %s >>./network/spoolout/remote_system_name
-
- This simply stores the outbound spool data in a file in the "spoolout"
-directory, where it will be picked up by server-to-server transfer programs.
-
- After the command line you should enter the names of all the rooms you
-intend to share with this system. Each room name should be followed by a
-line containing a zero - this extra field is the "last message sent" (which
-will be updated by netproc when it is run). Here is a sample systems file for
-a node called uncnsrd:
-
-cat %s >>./network/spoolout/uncnsrd
-Network Test
-0
-Gateway
-0
-The Room
-0
-
- The rooms "Network Test", "Gateway", and "The Room" will be spooled to
-the remote system. These rooms should be designated as network rooms with
-the .<A>ide <E>ditRoom command.
-
-
- USING NETPROC
-
-
- Calling netproc with no arguments causes it to look in the network/spoolin
-directory for newly arrived messages, and posts them if it finds any. It then
-automatically batches up new messages on your system to be sent to your net
-neighbors, and exports those messages to them. It is recommended
-that you use the cron program to handle your network processing on a routine
-basis automatically. Arrange with your netneighbors for both of your systems
-to batch new messages before actual polls take place, to guarantee that
-messages travel across the network as quickly as possible.
-
- Calling netproc with the -i flag causes it to skip the export phase, and
-handle incoming messages only.
-
-
- USING CITADEL/UX AS YOUR LOCAL E-MAIL SYSTEM
-
- This has changed markedly in the last few versions. Citadel used to require
-extensive patching into your system's MTA. Now it is a fully functional
-standalone e-mail system, complete with its own SMTP, POP3, and IMAP4
-implementations. Please refer to "inetmailsetup.txt" for more information.
-
-
- MAIL ALIASES
-
- The file network/mail.aliases is a simple list of aliases for the various
-mailers to use. Each line takes the form
-
-alias,name
-
- Obviously, neither the alias nor the name can contain commas. The name
-may also be the system name "sysop", where messages sent to sysop will
-be posted in the Aide> room.
-
-
- CITADEL/UX NETWORK MAIL
-
- Citadel/UX has the ability to transport mail in a simple and
-transparent fashion not unlike the way public messages are sent. Users may
-enter recipient names exactly as they appear on top of messages (i.e.,
-user name @ system name). In addition, mail routing is provided, allowing
-users to send mail to systems which do not directly connect with their own.
-
- When entering a message in the Mail> room, a user may type a recipient
-name on the local system, or on a remote system. If the recipient is not
-local, citadel.c calls netmailer.c, which is a standalone program that handles
-network mail. This runs in a multithreaded mode, allowing netmailer to run in
-the background while the user goes on to do something else.
-
-
- INTELLIGENT NETWORK PROCESSING AND THE MAIL.SYSINFO FILE
-
- There is (or soon will be) a file in your network directory called
-"mail.sysinfo". In earlier releases of the network software, the system
-administrator had to manually configure this file. Starting with netproc
-version 2.1, the system should now create and configure the file automatically.
-Note that all information may not appear in the file immediately. When a
-message arrives from a system on the network, your system will attempt to
-add that system to its network map. If the originating system is one of your
-netneighbors, it will look for a systems file in the network/systems directory
-to determine whether it is a valid neighbor. If the originating system is
-not a neighbor, but the message arrived via a valid neighbor, your map will
-be updated accordingly, with an entry for the new system showing the next hop
-to get there.
-
- So, under normal circumstances you shouldn't have to configure this file at
-all. But if you need to do something special, or if for some reason netproc
-detects the topology wrong, here's how to configure mail.sysinfo. There
-are three types of entries in this file. A "use" entry tells the system which
-neighbor to route a message through to get to a particular non-neighboring
-system. A "bin" entry tells the system that a particular neighbor supports
-net mail. If there are systems that either do not have the netmailer or are
-not running Citadel/UX, but can be reached by regular electronic mail, you
-can use the "uum" command. Type "uum" followed by an address (for the user
-name, use a %s which will be replaced by the user name at the remote
-system. Here is a sample network map, where our system is called "myself"
-and all systems have Citadel/UX EXCEPT for "gateway" and "mailsys":
-
- gateway---mailsys _____testbbs
- / /
- othersys ----- myself ----- thebox
- / \_______theirsys
- funboard
-
- In this example, our neighbors are "othersys" and "thebox". othersys
-also connects to funboard, and thebox connects to testbbs and theirsys. If
-everyone supports netmail, the network/mail.sysinfo file would look like this:
-
-funboard
-use othersys
-
-testbbs
-use thebox
-
-theirsys
-use thebox
-
-othersys
-bin Mail
-
-theirsys
-bin Mail
-
-gateway
-uum othersys!gateway!%s
-
-mailsys
-uum othersys!gateway!mailsys!%s
-
- (Keep in mind that your file will contain additional system-generated
-information.)
-
- The "bin" entries specify neighbors, the "use" entries specify routing, and
-the "uum" entries specify Internet mail. The method of delivery is totally
-transparent to the user, who only needs to enter the recipient as user@sysname.
-Note that netproc will probably stuff lots of other info into each entry.
-
-
- THE KILL FILE
-
- Tired of idiots lowering the quality of the net? You can set up a "kill
-file" in ./network/filterlist that can be used to filter out messages from
-any user, room, or system (or any combination). The three fields should be
-separated by commas, and the name "*" may be used as a wildcard in any field.
-Examples:
-
- # Filter out user "The Idiot" in "Idiot Room" at "idiotbbs"
- #
- The Idiot,Idiot Room,idiotbbs
-
- # Filter out the same user, but in every room
- #
- The Idiot,*,idiotbbs
-
- # Filter out all messages from a system we don't like
- #
- *,*,idiotbbs
-
- # Filter out messages in a certain room from a certain system
- #
- *,The Room,idiotbbs
-
- You could also put a "*" wildcard in all three fields, essentially
-disabling all incoming messages. Obviously you don't want to do this.
-
-
- CONCLUSION
-
- That should cover everything you need to get running. By the way, gateway
-software for StoneHenge and NYTI FordBoard systems is available upon special
-request. And, a Cit86Net gateway is now available. For the latest version
-of this program, or to leave comments/suggestions, visit UNCENSORED! BBS at
-uncensored.citadel.org.
Having come this far, you're ready to set up your networked rooms. In
and of itself it's not too difficult. I would suggest telnetting to
another Citadel/UX and checking out what they offer. Currently,
-uncnsrd.mt-kisco.ny.us and dogpound2.citadel.org and pixel.citadel.org
+uncensored.citadel.org and dogpound2.citadel.org and pixel.citadel.org
are your best bets.
Below is a list of the networked rooms (most of them) that PixelBBS
2. Contact me, or the sysop on another networked citadel (login to the
bbs and send mail to recipient Sysop), asking to share those rooms with
you.
-
- 3. From your Citadel/UX home directory (eg. /home/citux/citadel) run the
- program ./dnetsetup. Here it gets a little confusing so I'll paste
- in the actual menus where possible:
-
-
- **********************************************************************
- * Citadel/UX Network Setup *
- * *
- * ****************************************************************** *
- * * EDIT View or change a network node * *
- * * ADD Add a new network node * *
- * * DELETE Delete a network node * *
- * * EXIT Exit from Network Setup * *
- * ****************************************************************** *
- * *
- **********************************************************************
-
- **********************************************************************
- * < OK > <Cancel> *
- **********************************************************************
-
-
-
-
-
- As you can see above the menu choices are fairly clear. Lets go
-through the steps to actually setting this up.
-
- First, you'll need to add your network node. A node is the other Citadel/UX
-that is going to share rooms with you.
-
- Select A, then type in the name of your remote node, EXACTLY as that node's
-administrator has given it to you. In the case of PixelBBS that would be:
-
- pixel
-
- Note that the standard Citadel/UX convention is to use all lowercase. Using
-uppercase in the set up of your Citadel/UX has a tendency to do weird things
-like broadcast your net messages in triplicate, for example.
-
-Once you've added your network node, tab down to 'ok' and dnetsetup will
-take you back to the main screen. From here you need to edit your
-network node. Select option "E"dit and you should only have one node
-listed at this point:
-
- Select the node you wish to edit
-***********************************************
-* pixel *
-***********************************************
-
-***********************************************
-* <OK> <Cancel> *
-***********************************************
-
-
-Hit ok, at this point. You'll be given another list of options:
-
-
- Editing pixel
-************************************************
-* LIST List currently shared rooms *
-* SHARE Add a shared room *
-* UNSHARE Stop sharing a room *
-* EXIT Return to main menu *
-************************************************
-
-
-This list is fairly self evident, but I'll explain it anyhow:
-
- LIST shows you all the rooms you've setup to network with
- this node.
- SHARE allows you to ADD a networked room to network with this
- node.
- UNSHARE Stops networking specified rooms with this node.
-
-
-Simple enough, right? Ok, let's add a room. Remember that list of
-networked rooms? It's a good idea to have printed that out at this
-point. Here's where the fun begins. I'm only going to show how to add
-one room, all the rest you can do yourself.
-
-Select "S"HARE:
-
- Enter name of room to share:
-********************************************
-*House of Pork *
-********************************************
-
-
-********************************************
-* <OK> <Cancel> *
-********************************************
-
- Select ok, and bang, you've setup up the first portion of networking.
- Special note: The case of the rooms must be EXACT, so watch your
- capitalization!!
-
-
- When you're all finished adding the networked rooms that you'd like to
- share, jump out to the main menu and exit. You've finished (almost) with
- the networking part. Now we have to create the new rooms on the bbs
- itself.
-
-
- 4. Login to your BBS and type .er (. Enter a new Room).
- We'll assume for sake of argument that you are creating a publicly
- accessible, non directory, networked room:
-
-Lobby> . Enter a new Room
-Name for new room? House of Pork (again, watch your case!)
-<?>Help
-<1>Public room
-<2>Guess-name room
-<3>Passworded room
-<4>Invitation-only room
-Enter room type: 1
-"House of Pork", a public room.
-Install it? (y/n) : Yes
-(0 messages)
-House of Pork>
-
- Ok great. We've created it. Now, let's make it a networked room. Note
- that at the end of the roomname we've got a > instead of a ).
- When editing a room all options in [] are defaults, and you can simply
- hit enter to accept them.
-
-. Aide Edit this room
-Room name [House of Pork]:
-Private room [No]?
-Preferred users only [No]?
-Read-only room [No]?
-Directory room [No]?
-Permanent room [No]? Yes
- (note that directory and networked rooms are ALWAYS
- permanent, by default, however just to be safe,
- select 'y'es here.)
-Network shared room [No]? Yes
-Automatically make all messages anonymous [No]?
-Ask users whether to make messages anonymous [No]?
- (note: This assumes that the networked rooms you're
- creating is NOT an anon room)
-Room aide (or 'none') [none]:
- Up to you, on this one.
-Save changes (y/n)? Yes
-Ok.
-
- There. You've created and edited a network room. You'll note that the
- name's changed from: House of Pork> to House of Pork). Once you see the
- ) you've done it. :)
-
-
-
- There ya go. You've now successfully shared and created a node and a
- network rooms. All set.
-
- Well no. Firstly you need to make sure that you've been shared on the
- other node. Make sure and check on it, before going any farther. We'll
- assume for sake of argument that everything's set up on your remote node
- and you're all ready to go.
-
- There are two commands that are ABSOLUTELY vital for processing your
- networked messages. These are:
-
- netproc
- netpoll
-
- Netproc simply takes any messages that you've placed in a networked room
- on your BBS and spools them to an outbound queue:
-
- ~bbs/network/spoolout
-
- netpoll is the command that actually goes out to your remote network node
- and snags new messages. Once it has them it brings them back into Citadel/UX
- and parses them out to their proper rooms. Simple enough.
-
- The command netproc runs by itself, no flags needed. To run netpoll,
- you need to know a little bit about your remote node.
-
- What port is Citadel/UX running on? (Normally 504, but there are some strange
- people out there)
- What is the networking password?
-
- Once you have those, polling for your messages is easy, provided
- everything's been set up properly. Syntax for netpoll:
-
- netpoll bbs.address.org Citadel/UX port # networking password
-
- Eg: netpoll pixel.citadel.org 504 netpswd
-
- (No the above is NOT my password. We'll get into that later.)
-
- Once you run netpoll as stated above this should happen:
-200 pixel Citadel/UX server ready.
-Connected to: pixel (PixelBBS) Christiana, DE
-200 authenticated as network node 'yournodename'
-200 483
-200 Ok
-200 Ok
-
- What this says is that you've connected to the pixel server
- and that you've gotten the right password.
- 483 is the byte count of the messages that are coming down to you.
- The rest is stating that your messages have been uploaded and that
- you've terminated connection with the server. At this point you
- should check your networked rooms on the BBS and see what new messages
- await.
- You might want to automate this procedure by running it as a cron task.
-
- Here's mine:
-
- # Citadel/UX netprocessing tool
- 0,15,30,45 * * * * /home/citux/citadel/netproc > /dev/null 2>&1
- # Citadel/UX network message sender/receiver
- 5 * * * * /home/citux/citadel/netpoll dogpound2.citadel.org 504 netpswd > /dev/null 2>&1
-
- I hate having messages pop up everytime netproc/netpoll runs so I
- redirect the output to /dev/null.
- Every 15 minutes netproc runs and processes outbound messages.
- At 5 minutes after each hour netpoll sends all messages and imports new
- ones.
-
+
+ 3. Configure your neighbor nodes with <.A>ide <S>ysconfig <N>etwork
+
+ 4. Configure rooms to share with <.A>ide <N>etwork room sharing
+
+
At this point we're all done. Oh I admit that you might run into
some problems, and if you do you can feel free to mail
smw@pixel.citadel.org with the subject Citadel Problems.
-
-
+
+
Visit PixelBBS at:pixel.citadel.org, login as bbs.
Or, if you prefer: http://pixel.citadel.org:2000
Lobby> . Aide System configuration General
Node name [uncnsrd]:
- Fully qualified domain name [uncnsrd.mt-kisco.ny.us]:
+ Fully qualified domain name [uncensored.citadel.org]:
Human readable node name [Uncensored]:
- Modem dialup number [US 914 244 3252]:
+ Modem dialup number [US 914 999 9999]:
Geographic location of this system [Mount Kisco, NY]:
Name of system administrator [IGnatius T Foobar]:
Paginator prompt [<jinkies! more text on the next screen!>]:
.<R>ead <I>nfo file command is entered.
.<A>ide <K>ill room Deletes the current room. Lobby>, Mail>, and
Aide> may not be deleted.
+ .<A>ide <L>ist management Sets up a room as a mailing list server.
.<A>ide <M>essage edit: Allows you to change various system banners, such
as the 'hello' logon greeting.
+ .<A>ide <N>etwork sharing Sets up sharing of a room with neighbor nodes.
.<A>ide <P>ost Enter a message using any user name.
.<A>ide <R>oom <I>nvite Invites a user to the room if it is private.
.<A>ide <R>oom <K>ickOut Kicks a user out of the room if it is private.
.<A>ide <S>ystem <G>eneral Edits global system configuration.
.<A>ide <S>ystem <I>nternet Edits your internet settings
+ .<A>ide <S>ystem <N>etwork Configures neighbor nodes for room sharing.
+ .<A>ide <T>erminate <N>ow Immediately shut down the Citadel service.
+ .<A>ide <T>erminate <S>ched Request a "scheduled shutdown" which will take
+ place the next time zero users are logged in.
.<A>ide <U>serEdit Edits certain parameters of a user's account.
.<A>ide <V>alidate newusers Lists users who have recently registered and
prompts for new access levels.
CONCLUSION
For more information, visit the Citadel/UX web site at UNCENSORED! BBS
- http://uncnsrd.mt-kisco.ny.us
+ http://uncensored.citadel.org
msgform reads standard input, scanning for binary messages, starting
with an <FF> byte and ending after the final NULL, and print as many as it
finds until it encounters EOF.
- You could use this utility along with netproc to provide printouts or
-archives of certain rooms.
USERLIST
IPGM is a low-level command that should not be used by normal user clients.
It is used for various utilities to communicate with the server on the same
-host. For example, the networker (netproc.c) logs onto the server as an
-internal program in order to fetch and store messages. Since user clients
+host. For example, the "sendcommand" utility logs onto the server as an
+internal program in order to run arbitrary server commands. Since user clients
do not utilize this command (or any of its companion commands), developers
writing Citadel-compatible servers need not implement it.