Moved install.txt to docs.
Added inetmailsetup.txt (BBS server side e-mail)
Added inetmailsetupmx.txt (local mail AND bbs e-mail
Added inetsiteconfig.txt (describes the .asi command)
Added siteconfig.txt (describes .asg)
Added chat.txt (describes changes and new chat functionality)
Made a couple of changes to install.txt (references to new documentation)
Added Steve Williams to copyright.txt as the document writer.
-$Log$
+ $Log$
+ Revision 1.489 2000/03/16 17:58:54 smw
+ Created a docs directory.
+ Moved install.txt to docs.
+ Added inetmailsetup.txt (BBS server side e-mail)
+ Added inetmailsetupmx.txt (local mail AND bbs e-mail
+ Added inetsiteconfig.txt (describes the .asi command)
+ Added siteconfig.txt (describes .asg)
+ Added chat.txt (describes changes and new chat functionality)
+ Made a couple of changes to install.txt (references to new documentation)
+ Added Steve Williams to copyright.txt as the document writer.
+
Revision 1.488 2000/03/15 03:04:51 ajc
* Added DEXP server command to disable incoming express messages.
* <Q>uiet mode client side command to set/clear DEXP mode.
Portions (c) 1998-2000 by Nathan Bryant, Brian Costello, and Ben Mehlman.
+Documentation (c) 2000 by Steve Williams.
+
base64 encoding/decoding for MIME parser, public domain by John Walker.
ICQ client code derived from ICQLIB written by Denis V. Dmitrienko.
--- /dev/null
+
+
+
+The Citadel/UX Chat program functions very much like IRC. Similar '/'
+commands, etc. For those of you who have been using Chat, the 5.7x and
+above versions of Citadel/UX have a slightly different functionality for
+Chat than you're used to....chat now follows the room that you are in. If
+you are in an invite only room for example and type 'c' to get into chat
+ONLY the people that are invited into that room will be able to access
+that chat room. Basically thus: If you are in a public room (call it
+General Babble) and there are other users at the General Babble> prompt
+they will all be able to chat in that room. If there are other users in
+other chat rooms that will show up when you start chat:
+
+General Babble> Chat
+Entering chat mode (type /quit to exit, /help for other cmds)
+
+:: Note: you are the only one here.
+ There are 2 users chatting in other rooms.
+
+
+Test: (entering chat)
+
+::
+ Users currently in chat:
+ Test (General Babble(chat)):
+ Patriot (Lobby (chat)):
+ IGnatius T Foobar (private room (chat)):
+
+>
+
+
+
+As you can see, user Test is in the General Babble chat room, while user
+'Patriot' is in the Lobby chat room and IG's in an invite only room. Note
+that unless they're in the SAME chat room they won't see each other's
+messages.
--- /dev/null
+
+
+
+Citadel/UX Internet E-mail setup instructions (native Citadel/UX version)
+
+This document explains how to set up your citadel as an Internet e-mail
+capable system. Once you are through with this document you should be able to
+have your users send mail from, and receive mail to
+systemname@system.citadel.org. For example to send e-mail to a user at
+Uncensored! BBS via e-mail you would do the following:
+mail Patriot@uncnsrd.citadel.org
+
+To set this up is almost insanely simple.
+
+ 1. Check for the existance of a current MTA (sendmail, qmail, etc):
+ If you see something similar to the following you're running an MTA
+ already and you'll need to shut it down:
+
+
+ smw @ pixel % telnet localhost 25
+ Trying 127.0.0.1...
+ Connected to localhost.
+ Escape character is '^]'.
+ 220 pixel.citadel.org ESMTP Sendmail 8.9.3/8.9.3; Wed, 15 Mar 2000 19:00:53 -0500
+
+
+
+
+ The above shows that pixel is running Sendmail version 8.9.3 and the
+current date. What this means is that Pixel is running the MX version of
+bbs e-mail, which is described in inetmailsetupmx.txt.
+
+If you get a 'connection refused' message when you telnet to port 25 there's
+nothing running and you should be able to continue. You might also want to
+turn off pop (try the above test substituting 110 for 25) and use
+citadel's pop server.
+
+This pop server will ONLY allow pop'ing of mail for your BBS users.
+For those of you who are running some kind of mail transport agent
+(as Pixel is, above) or pop server, the following will show how to remove
+it from a RedHat Linux system:
+
+
+ Removing Sendmail
+
+ First cd to /etc/sysconfig.
+ As root, change (I don't recommend actively removing files
+ unless you REALLY know what you're doing) the sendmail file to
+ sendmail.old or move it from that directory completely.
+ Shut down sendmail.
+ You can either reboot or /etc/rc.d/init.d/sendmail stop, OR do a
+ ps and kill sendmail manually. Your method of choice is up to you.
+
+ Removing Pop
+
+ cd /etc and edit inetd.conf. Look for a few lines similar to:
+
+ # Pop and imap mail services et al
+ #
+ #pop-2 stream tcp nowait root /usr/sbin/tcpd ipop2d
+ #pop-3 stream tcp nowait root /usr/sbin/tcpd ipop3d
+ #imap stream tcp nowait root /usr/sbin/tcpd imapd
+
+
+ If they're already commented out you're good to go for the
+ Citadel/UX server to take over pop. If not, you'll want to
+ comment them out.
+
+ 2.Ensure you have the correct FQDN in (.A)ide (S)ystem (G)eneral
+ This is explained in siteconfig.txt.
+ 3.Add any alias FQDN's in (.A)ide (S)ystem (I)nternet
+ Explained in inetsiteconfig.txt.
+ 4.Add a Smart Host, if you need one.
+ 5.Restart your Citadel/UX server.
+
+
+
+Some definitions:
+
+ FQDN: Fully Qualified Doman Name:
+ If your system were called 'test' on the foobar.com network, and you
+ had an entry on the internet by which you could get to your system
+ your FQDN would be test.foobar.com. For the most part, most FQDNs
+ will be your bbsname.citadel.org. Coordinate that with Freakdog on
+ DogpoundII (telnet://dogpound2.citadel.org).
+
+ Alias FQDN:
+ Other names by which your system can be called.
+
+ Smart Host:
+ An internet host that relays your mail for you, or a host to which
+ you would send ALL your mail which could go out via an MX record.
+
+
+
+Citadel will look for an existing pop/smtp server on startup. If they don't
+exist (and you've configured them as shown in siteconfig.txt) citadel should
+fire them up at start time. You can check your logs to be sure, or you can
+start the server from a shell and watch it load. It should look similar to
+this:
+
+
+smw @ pixel % ./citserver
+
+Multithreaded message server for Citadel/UX
+Copyright (C) 1987-2000 by the Citadel/UX development team.
+Citadel/UX is free software, covered by the GNU General Public License, and
+you are welcome to change it and/or distribute copies of it under certain
+conditions. There is absolutely no warranty for this software. Please
+read the 'COPYING.txt' file for details.
+
+Loading citadel.config
+Opening databases
+This is GDBM version 1.8.0, as of May 19, 1999.
+Checking floor reference counts
+Creating base rooms (if necessary)
+Registered a new service (TCP port 504)
+Registered a new service (TCP port 0)
+Initializing loadable modules
+Registered server command CHAT (Begin real-time chat)
+Registered server command PEXP (Poll for express messages)
+Registered server command GEXP (Get express messages)
+Registered server command SEXP (Send an express message)
+Registered server command DEXP (Disable express messages)
+Registered a new session function (type 0)
+Registered a new x-msg function (priority 0)
+Loaded module: $Id$
+Registered a new session function (type 1)
+Registered a new message function (type 201)
+Registered a new message function (type 202)
+Registered server command REGI (Enter registration info)
+Registered server command GREG (Get registration info)
+Registered a new user function (type 100)
+Loaded module: $Id$
+Server-hosted upgrade level is 5.62
+Loaded module: $Id$
+Registered server command EXPI (Expire old system objects)
+Registered server command FSCK (Check message ref counts)
+Loaded module: $Id$
+citserver: Can't bind: Address already in use
+ERROR: could not bind to TCP port 25.
+Registered a new service (TCP port 0)
+Registered a new session function (type 50)
+Loaded module: $Id$
+citserver: Can't bind: Address already in use
+ERROR: could not bind to TCP port 110.
+Registered a new session function (type 0)
+Loaded module: $Id$
+Registered a new message function (type 202)Loaded module: $Id:
+serv_inetcfg.c,v 1.2 2000/02/03 03:57:35 ajc Exp $
+Registered server command RWHO (Display who is online)
+Registered server command HCHG (Masquerade hostname)
+Registered server command RCHG (Masquerade roomname)
+Registered server command UCHG (Masquerade username)
+Registered server command STEL (Enter/exit stealth mode)
+Loaded module: $Id$
+Changing uid to 513
+Starting housekeeper thread
+
+Notice the two error lines below:
+citserver: Can't bind: Address already in use
+ERROR: could not bind to TCP port 110.
+
+This means that Citadel couldn't start up pop services. Generally this
+only happens if there's something on this port. In this case it's Pixel's pop
+server (incidentally, PixelBBS uses Citadel/UX for pop).
+
+citserver: Can't bind: Address already in use
+ERROR: could not bind to TCP port 25.
+
+This occurs whenever something is on port 25. In this case sendmail is
+there. Make SURE you've followed the above steps to remove sendmail/pop and
+start your server again.
--- /dev/null
+
+
+
+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
+only pertains if you want to have local e-mail as WELL as BBS e-mail. If
+you want ONLY your BBS users to be able to receive Internet e-mail check
+out mailsetup.html.
+
+Note: These instructions were created using Sendmail 8.9.3. Earlier
+versions in the 8.8/8.9 line should still work, but prior to 8.8 this is
+not going to work. If you're using postfix or some aother mail server
+you're pretty much on your own, but please mail Patriot @pixel, or
+smw@pixel.citadel.org and let me know your configurations so I can add
+them to this document.
+
+
+ 1.Set up an MX record for your site.
+ Probably the most important step is this first one. This will ONLY
+ work if your internet coordinator (Freakdog @dogpound2,
+ mburger@compucomis.net if you're in the citadel.org domain) sets up
+ an MX record for your site. Or, if you have your own domain, set up
+ an MX record to point to your site. For purposes of examples I'm
+ going to use pixel (my BBS) to show the setups. Pixel is set up as
+ pixel.citadel.org. Here's what the MX record should like
+ like in DNS on a machine in the citadel.org domain:
+
+ bbs.pixel IN MX 10 pixel
+
+
+ This sets up an MX (mail exchange) id for your host and says that
+ incoming mail for bbs.pixel.citadel.org is accepted by
+ pixel.citadel.org. Once this is set up, you should be
+ able to verify it with nslookup. Check out the nslookup session I ran
+ for Pixel, below:
+
+ smw @ pixel % nslookup
+ Default Server: ns1.dca.net
+ Address: 204.183.80.2
+
+ > set type=mx
+ > bbs.pixel.citadel.org
+ Server: ns1.dca.net
+ Address: 204.183.80.2
+
+ bbs.pixel.citadel.org preference = 10, mail exchanger = pixel.citadel.org
+ citadel.org nameserver = linux.compucomis.net
+ citadel.org nameserver = linux2.compucomis.net
+ citadel.org nameserver = uncnsrd.mt-kisco.ny.us
+ citadel.org nameserver = mansrv.manhasset.techsoftwareinc.com
+ pixel.citadel.org internet address = 207.245.90.41
+ linux.compucomis.net internet address = 207.8.143.10
+ linux2.compucomis.net internet address = 207.8.143.13
+ uncnsrd.mt-kisco.ny.us internet address = 168.100.205.221
+ >
+
+ As you can see pixel.citadel.org is listed as a mail exchanger for
+ bbs.pixel.citadel.org. Since you can see that with nslookup the
+ changes are out there and you're ready to get started.
+
+ 2.Set up sendmail
+
+ Sendmail has 'mailertable' functionality. If you already are running
+ sendmail with mailertable you can pretty much skip this step. If not,
+ read on:
+
+ Locate the mailertable entry in /etc/sendmail.cf. (Kmailertable hash -o
+ /etc/mail/mailertable.db) and uncomment it.
+ Search for the word 'mailertable again'. You should eventually
+ find an entry similar to this:
+
+
+ # not local -- try mailer table lookup
+ R$* <@ $+ > $* $: < $2 > $1 < @ $2 > $3 extract host name
+ R< $+ . > $* $: < $1 > $2 strip trailing dot
+ R< $+ > $* $: < $(mailertable $1 $) > $2 lookup
+ R< $~[ : $* > $* $>95 < $1 : $2 > $3 check -- resolved?
+ R< $+ > $* $: $>90 <$1> $2 try domain
+
+ This entry should look similar to yours, and should NOT be
+ commented out. Be sure that it's uncommented.
+ Add the entry for citadel to be a local mailer:
+ Search for Mlocal, in sendmail.cf. Add the following after the
+ Mprog section:
+
+
+ Mcitadel, P=/usr/local/citadel/citmail, F=lsDFMoqeu9S, S=10/30, R=20/40,
+ D=$z:/, T=X-Unix, U=bbs,
+ A=/usr/local/citadel/citmail $u
+
+
+ Notice /usr/local/citadel is the path to Pixel's citadel home
+ directory. Replace this witha your citadel's home dir.
+
+ Set up the mailertable itself: In the Kmailertable line above
+ there was a path to your
+ mailertable. In this case it's /etc/mail/mailertable.db. For
+ this example that's the file we'll use. cd /etc/mail and edit
+ mailertable. (don't worry if there's no file there called
+ mailertable. Simply create a new one.) This is the mailertable
+ for pixel:
+
+
+ bbs.pixel.citadel.org citadel:localhost
+
+
+ Please note that the whitespaces are tabs. You need one after
+ bbs.mysite.org and citadel:localhost.
+ Compile the mailertable.
+ makemap -v hash mailertable.db < mailertable
+ That line simply makes a readable hashed database that sendmail
+ can read out of the mailertable entry you created. For the
+ entry above this should look similar to this:
+
+ key='bbs.pixel.citadel.org', val='citadel:localhost'
+
+ Restart sendmail. If you're running later releases of Red Hat
+ Linux (for example) you can just do: /etc/rc.d/init.d/sendmail
+ restart. For others use the kill/restart method that works best
+ for you.
+
+ 3. In your bbs now, do a .as and change your FQDN to reflect your new MX
+ record. You should NOT have to restart citadel:
+
+ Lobby> . Aide System configuration
+ Node name [pixel]:
+ Fully qualified domain name [bbs.pixel.citadel.org]:
+
+
+
+A few notes:
+
+ 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
+bbs.pixel.citadel.org. In later versions of sendmail relaying is turned
+off by default. Check sendmail.cf for the following line:
+
+ FR-o /etc/mail/relay-domains
+
+If that line is commented out you're allowing relaying from any host.
+Not recommended. I won't tell you how to run your sendmail but it's
+usually better NOT to relay. If that line is commented out, no problems
+(aside from the obvious spam issues with relaying for the entire
+planet.:). If it isn't commented out udpdate/create the file
+
+ /etc/mail/relay-domains
+
+and put your new entry in it. For pixel this is: bbs.pixel.citadel.org.
+
+
+
+Please contact me with questions/problems or just to let me know it's up
+and running. I'd be interested in hearing from folks. smw@pixel.citadel.org
--- /dev/null
+
+
+
+
+This document explains the (.A) (S)ystem (I)nternet command.
+
+Lobby> .Aide System Configuration Internet
+
+### Host or domain Record type
+--- -------------------------------------------------- --------------------
+ 1
+(A)dd (D)elete (S)ave (Q)uit ->
+
+This is a 'clean' set up. Pixel uses the mx method because we have local
+users who get e-mail on the system. Basically to get all set up for mail
+you simply have to type <a>dd:
+
+(A)dd (D)elete (S)ave (Q)uit -> Add
+
+Enter host name: pixel.citadel.org
+ (1) localhost (Alias for this computer)
+ (2) gateway domain (Domain for all Citadel systems)
+ (3) smart-host (Forward all outbound mail to this host)
+
+Which one [1]:
+
+Basically what you're doing here is telling Citadel what any aliases for
+your machine are. If your machine were pixel.somedomain.com and you also
+had a DNS entry set up byFreakdog (freakdog @dogpound2), you might want to
+put in pixel.citadel.org as your alias, so that e-mail sent to that
+address won't bounce.
+
+Gateway Domain:
+citadel.org (that's the current domain for Citadel/UX systems)
+
+smart-host:
+A host to which you send all e-mail to be forwarded to the Internet. In
+most cases you won't need this, however I speak from experience when I say
+that if you don't have a static IP and domain name (the citadel.org
+addresses are dynamically assigned) a lot of MTA filters will block
+mail from your address. So unless you have a static domain, you'll
+probably want to send mail through a smart host. Usually your ISP will
+provide you with that information.
+
+All you have to do is save and you're done.
--- /dev/null
+ Citadel/UX Installation Procedure
+ See copyright.txt for copyright information
+
+
+ OVERVIEW
+
+ Citadel/UX is an advanced, multiuser, client/server, room-based BBS
+program. It is designed to handle the needs of both small dialup systems and
+large-scale Internet-connected systems. It was originally developed on an
+Altos system running Xenix, and has been installed and tested on various
+Unix and Unix-like platforms. The author's current development environment
+(and BBS) is a Linux/GNU system. The current distribution includes:
+
+ - The Citadel/UX server (this is the back end that does all processing)
+ - A text-based client program designed with the traditional Citadel "look
+ and feel" (room prompts, dot commands, and the like)
+ - A networker that can share rooms and email between multiple systems.
+ Replication can be performed via TCP/IP or any external transport.
+ - Setup programs
+ - A rich set of utilities for system administration and maintenance
+ - Documentation
+
+ Some knowledge of the Unix system is necessary to install and manage the
+system. It is preferable that the sysop have superuser access to the operating
+system. The following are required to install Citadel/UX:
+
+ - A Unix operating system (Linux, BSD, Solaris, DEC Unix, etc.)
+ - C compiler (such as gcc or egcs) and "make"
+ - POSIX threads
+ - TCP/IP
+ - The "gdbm" record manager
+ - Enough disk space to hold all of the programs and data
+
+ If you are running Citadel/UX on a Linux system, it is STRONGLY recommended
+that you use a version based on glibc v2 (also called libc6). libc5 contains
+a number of thread safety problems. Furthermore, most modern Linux
+distributions have libc6, pthreads, gdbm, and the compiler already installed
+and integrated for you.
+
+
+ NOW AVAILABLE:
+
+ - "WebCit", a gateway program to allow full access to Citadel/UX BBS's
+ via the World Wide Web. Interactive access through any Web browser.
+
+ COMING SOON:
+
+ - Newer and better GUI based clients.
+
+
+
+ EVERYTHING IN ITS PLACE...
+
+ Hopefully you've unpacked the distribution archive into its own directory.
+This is the directory in which all Citadel files are located and in which all
+BBS activity will take place. Several subdirectories have already been created
+during the unpacking process, and others may be created by the software if
+needed.
+
+ Make sure you have the "gdbm" record manager installed on your system, and
+that you have installed the libraries and headers required to compile gdbm
+programs. Likewise, if your operating system uses a separate library to
+support POSIX threads, make sure that library is installed as well.
+
+
+ THE BBS LOGIN
+
+ There will be one account in /etc/passwd which all BBS users will use to
+login to the system. This account is typically called "bbs" or "citadel" or
+something to that effect. You will tell Citadel what the user-id of that
+account is, and when someone logs in under that account, Citadel will prompt
+for a user name.
+
+The BBS login should have a unique uid. The home directory should be the
+one your BBS resides in (in this example we will use /usr/citadel) and the
+shell should be either "citadel" in that directory, or a script that will start
+up citadel (you may wish to set up an external text editor; see below).
+Example:
+
+ bbs::100:1:BBS Login:/usr/citadel:/usr/citadel/citadel
+
+ When you run setup later, you will be required to tell it what the BBS
+login's numeric user ID is, so it knows what user to run as. If you create
+an account called bbs, guest, or citadel, the setup program will automatically
+pick up the user ID by default.
+
+ For all other users in /etc/passwd, Citadel will automatically set up an
+account using the "full name" field. No password is required, since it
+assumes that if a user is logged in, he/she has already entered a password.
+Note that this does have to be enabled at compile time (see ENABLE_AUTOLOGIN
+in the Makefile). If such an account needs to be accessed remotely (such as
+from client software), these users can use *either* their Citadel login name
+or their login name on the host computer, and their password on the host
+computer.
+
+
+ COMPILING THE PROGRAMS
+
+
+ You can easily compile Citadel with the following commands:
+
+ ./configure
+ make
+ make install
+
+ The 'configure' script will generate a Makefile from the Makefile.in, and
+it will also write the file "sysdep.h" to your Citadel directory. Please do
+not edit sysdep.h or Makefile.in yourself. The configure script will figure
+out your system dependencies and set everything correctly.
+
+ By default, the Citadel system will install in /usr/local/citadel. If you
+wish to place it in a different directory, you can instead do:
+
+ ./configure --prefix=/opt/citadel (or whatever)
+
+
+ File permissions are always a bother to work with. You don't want the
+board to crash because someone couldn't access a file, but you also don't
+want shell users peeking into the binaries to do things like reading others'
+mail, finding private rooms, etc. The Citadel server needs to be started
+as root in order to bind to a privileged port, but as soon as its
+initialization is finished, it changes its user ID to your BBS user ID in
+order to avoid security holes.
+
+
+ THE CITADEL.RC FILE
+
+ This is a change from the way things were done before. All client-side setup
+is in a "citadel.rc" file. The standard client looks for this file in:
+ 1. $HOME/.citadelrc
+ 2. /usr/local/lib/citadel.rc
+ 3. <compiled BBSDIR>/citadel.rc
+
+ The next couple of sections deal with client-side configuration.
+
+ USING AN EXTERNAL EDITOR FOR MESSAGES
+
+ Citadel/UX has a built-in message editor. However, you can also use your
+favorite text editor to write messages. To do this you simply put a line in
+your citadel.rc file like:
+
+editor=/usr/bin/vi
+
+ ...would make Citadel call the vi editor when using the .<E>nter <E>ditor
+command. You can also make it the default editor for the <E>nter command by
+editing the citadel.rc file. (WARNING: external editors on public systems
+can create a security hole. Make sure there is absolutely no way for users
+to drop into the shell from the editor, or save files other than the temp file
+they are editing!)
+
+ Using this mechanism, shell users can pick their favorite editor for Citadel.
+BBS users can use external editors too; just have the bbs login call a script
+that sets the variables and then calls citadel. I used to recommend using
+an external editor as the default, but the built-in editor is now a bit more
+robust, so the use of an external editor is definitely optional. By the
+way, be VERY careful what editor you choose and how you set up its options.
+Giving the general public to an editor like vi or emacs can open up lots of
+security holes.
+
+
+ PRINTING MESSAGES
+
+ Citadel/UX can send messages to a printer, or just about anywhere else in
+your system. The variable PRINTCMD in citadel.rc specifies what command you
+use to print. Text is sent to the standard input (stdin) of the print command.
+
+ So if you did this:
+
+printcmd="nl|pr|lpr -dlocal"
+
+ ...that would add line numbers, then paginate, then print on the printer
+named "local". There's tons of stuff you can do with this feature. For
+example, you could use a command like "cat >>$HOME/archive" to save copies
+of important messages in a textfile.
+
+
+URL VIEWING:
+
+urlcmd=netscape -remote "openURL(%s)"
+
+...that would mean that typing 'u' in a room prompt after seeing a url in
+one of the room's messages netscape will open up for you and run that url.
+
+ SETUP AND LOGIN
+
+ Before logging in for the first time, you must run the setup program. Type
+"./setup" to begin this procedure.
+
+ The setup program will ask you what directory to place your data files in.
+You can use this functionality to keep your programs and data in different
+directories, or to run more than one BBS on the same computer. If you don't
+use the default directory (the one specified in the Makefile), remember to
+specify the directory name again when you start up the server later on.
+
+ If you've used older versions of Citadel/UX before, you'll notice that the
+setup program does much less than it did before. It won't create any empty
+data files; that's now done automatically by the server the first time it
+starts. It also asks only a few questions; that's because the rest of the
+global configuration is now done from within Citadel.
+
+
+ PREPARING TO START THE SERVER
+
+ The files /etc/services and /etc/inittab must be modified in order to run
+the Citadel server. The setup program will perform the correct modifications
+for you if you allow it to. If you'd prefer to do it manually, or if you're
+interested in what these modifications are, then read on...
+
+ Before you can use Citadel, you must define the "citadel" service to your
+system. This is accomplished by adding a line to your /etc/services file that
+looks something like this:
+
+ citadel 504/tcp # Citadel/UX Server
+
+ 504 is the port number officially designated by the IANA for use by Citadel.
+There should not be any need to use a different port number, unless you are
+running multiple BBS's on the same computer and therefore need a different
+port for each one.
+
+ The next step is to arrange for the server to start. The "citserver"
+program is the main Citadel server. Before we cover the recommended method of
+starting the server, let's examine its usage options:
+
+ citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-d] [-f]
+
+ The options are as follows:
+
+ -hHomeDir - the directory your BBS data files live in. This should, of
+course, be a directory that you've run the "setup" program against to set up
+some data files. If a directory is not specified, the directory name which
+was specified in the Makefile will be used.
+
+ -xDebugLevel - Set the verbosity of trace messages printed. The available
+debugging levels are:
+ 1 - Internal errors (failed thread creation, malloc problems, etc.)
+ 2 - Network errors (broken sockets, failed socket creation)
+ 3 - Begin and end of sessions, startup/shutdown of server
+ 5 - Server commands being sent from clients
+ 7 - Entry and exit of various functions
+ 8 - Entry and exit of critical sections
+ 9 - Various debugging checkpoints (insanely verbose)
+
+ -tTraceFile - Tell the server where to send its debug/trace output.
+Normally it is sent to stdout.
+
+ -d - Run as a daemon. This switch would be necessary if you were
+starting the Citadel server, for example, from an rc.local script (which is
+not recommended, because this won't allow the server to automatically restart
+when it is shut down).
+
+ -f - Defragment all the databases upon startup. This isn't
+normally necessary due to the nature of the data stored in Citadel, but the
+option is provided in case you need it.
+
+
+ The preferred method of starting the Citadel server is to place an entry in
+your /etc/inittab file. This will conveniently bring the server up when your
+system is up, and terminate it gracefully when your system is shutting down.
+The exact syntax for your system may vary, but here's the entry that I use on
+my Linux system:
+
+ cit:2345:respawn:/appl/citadel/citserver -h/appl/citadel -t/dev/tty6 -x3
+
+ What I've done here is to set debugging level 3, and have the trace stuff
+output to one of my virtual consoles. It's important to remember to turn off
+any getty that is set up on that virtual console, if you do this. After
+making this change, the command "init q" works on most systems to tell init
+to re-read the file. If in doubt, just reboot your computer.
+
+
+ LOGGING IN FOR THE FIRST TIME
+
+ At this point, your system is ready to run. Run the citadel program from
+the shell and it will automatically create your account. NOTE: the first
+user account to be created will automatically be set to access level 6
+(Aide). This overcomes some obvious logistical problems - normally, Aide
+access is given by another Aide, but since there aren't any on your system
+yet, this isn't possible.
+
+
+ SPACE FOR ADDING YOUR OWN FEATURES (doors)
+
+ *** PLEASE TAKE NOTE!! *** This function really represents the "old"
+way of doing things, and it doesn't fit in well with the client/server
+paradigm. Please consider it "deprecated" because it may be removed at any
+time.
+
+ The "doorway" feature is just a generic way to add features to the system.
+I called it "Doorway" to make it resemble the doors on non-Unix boards, but as
+we all know, us Unix types don't have to write special code to access the
+modem. :-) Anyway, when a user hits the <*> (doorway) command, Citadel does...
+
+ USERNAME=<username>; export USERNAME
+ ./subsystem <user number> <screen width> <access level>
+
+ ...so you can put whatever you want in there. I suggest putting in a menu
+program to allow the users to pick one of a number of programs, etc.
+
+ Do be aware that chat and door programs will only be available when two
+conditions are met:
+
+ 1. The client and server programs are running on the same computer
+ 2. The user is running the text-based Unix client.
+
+ Because of these restrictions, Door programs are being utilized less and
+less every day.
+
+
+
+
+ THE PEANUT GALLERY
+
+ That's just about all the information you need to install the system.
+ For more information, visit the Citadel/UX web site at UNCENSORED! BBS
+ http://uncnsrd.mt-kisco.ny.us
+
+ Please note: if you intend to report a problem getting the Citadel server
+to run, please first check the following:
+
+ 1. Did you do ./configure && make && make install ??
+ 2. Did you run setup?
+ 3. Did you start the server?
+
+ To report a problem, you can log on to UNCENSORED! or any other BBS on the
+Citadel network which carries the Citadel/UX> room. Please remember to mention
+all of the following information:
+
+ 1. The exact nature of your difficulty
+ 2. A transcript of the error message(s) if possible
+ 3. The version of Citadel you are running
+ 4. The version of GDBM present on your system
+ 5. Which operating system you are running, and what version
+ 6. If you are running a Linux system, we need to know which distribution, and
+the version of the kernel, libc, and pthreads you are using (it would help to
+post the output of a "ldd ./citserver" command).
+
+
--- /dev/null
+
+
+
+Site Configuration
+by IGnatius T Foobar
+
+ Once your Citadel server is up and running, the first thing you'll
+want to do is customize and tune it. This can be done from the
+text-based client with the .Aide System configuration General command,
+or from WebCit (if you have it installed) by clicking "Advanced Options"
+followed by "Edit site-wide configuration." This document will show the
+text client being used, but the available set of options are the same
+either way.
+
+ The first set of options deal with the identification of your system.
+
+
+ Lobby> . Aide System configuration General
+ Node name [uncnsrd]:
+ Fully qualified domain name [uncnsrd.mt-kisco.ny.us]:
+ Human readable node name [Uncensored]:
+ Modem dialup number [US 914 244 3252]:
+ Geographic location of this system [Mount Kisco, NY]:
+ Name of system administrator [IGnatius T Foobar]:
+ Paginator prompt [<jinkies! more text on the next screen!>]:
+
+
+
+For "node name" you should enter the "short" node name of your system. It
+is used in a number of places, most notably for routing of messages
+across a Citadel network. Citadel will attempt to set the default value
+to the unqualified host name of your computer.
+
+Then enter the fully-qualified domain name [FQDN] of your system. If you
+are not on the Internet, you can simply set it to the same as your
+unqualified host name. Otherwise you should
+set this value to the host name by which your system is most commonly known.
+
+The field "Human-readable node name" is also called the "node title" or
+"organization name." It is used primarily for display purposes. Set it to
+the actual name of your system as you want it to appear.
+
+If you have a modem or bank of modems answering data calls for your
+system, enter it in the field marked "Modem dialup number." Otherwise
+you may make something up. This is used for interoperability with older
+Citadel-86 systems which use a telephone number for node identification.
+
+"Geographic location of this system" is another display field. Enter a
+city and state, or city and country.
+
+"Name of system administrator" is important! Any user who logs on with
+the name you enter here will automatically be granted Aide privileges.
+This is one of two ways for the system administrator to grant
+himself/herself Aide access to the system when initially setting it up. (The
+other is simply to have the first account created on a new installation.)
+
+
+ The next set of options are your system's security settings. Before
+delving into the actual options, we should review the various access
+levels available on the system. Citadel has seven access levels:
+
+ 0 (Deleted). A user whose access level is set to 0 will
+ automatically be deleted by the system.
+ 1 (New User). Users at this level may only read messages. Entering
+ messages is prohibited, except in the Mail> room, where a message
+ to 'sysop' may be entered.
+ 2 (Problem User). Also known as "Twit."
+ 3 (Local User). May enter messages, except in rooms shared on a
+ Citadel network.
+ 4 (Network User). May enter messages in every accessible room.
+ 5 (Preferred User). Use of this level is up to the whim of the
+ system administrator.
+ 6 (Aide). Access is granted to the administrative functions of the
+ system. (This access level may also be granted to a user only for
+ a specific room, please see "Room Aide" for
+ more information.)
+
+
+ Require registration for new users [No]: No
+ Initial access level for new users [4]:
+ Access level required to create rooms [4]:
+ Automatically give room aide privs to a user who creates a private room [No]: No
+ Automatically move problem user messages to twit room [Yes]: Yes
+ Name of twit room [Trashcan]:
+ Restrict Internet mail to only those with that privilege [No]: No
+ Name of room to log pages [Page Log Scandal]:
+
+
+
+"Registration" refers to the process of a user entering various personal
+contact information (real name, address, telephone number, etc.) into the
+system. When enabled, this information is stored as a vCard object on
+the system in two places: the user's My Citadel Config> room, and in
+the Global Address Book> room. (Note: the latter should be made private
+on publicly-accessible systems, for obvious reasons.)
+
+If you answer Yes to "Require registration for new users" then each new
+user, upon creating a new account, will immediately be entered into the
+registration process.
+
+"Initial access level for new users" should be set to 1 (New User) if you
+would like to review each new user's registration info before granting
+them higher access. This would be done periodically with the <.A>ide
+<V>alidate-new-users command. If you do not require registration, you
+should set the initial access level to 4 (Network User).
+
+"Access level required to create rooms" is up to you. You might wish to
+restrict the creation of new rooms only to Aides, or you might wish to
+allow anyone to create a room. The latter is one of the Citadel
+culture's most long-standing traditions; the former may be appropriate if
+users are abusing this privilege.
+
+You have the ability to "Automatically give room aide privs to a user who
+creates a private room." If you answer Yes, then any user who creates a
+guess-name, passworded, or invitation-only room will automatically become
+the room aide, and will have access to a subset of the <.A>ide command
+set while in that room. If you would rather grant this permission
+manually, answer No.
+
+Another tradition in the Citadel culture is to refrain from deleting
+problem users, but instead to "twit" them (reduce their access level to 2
+[Problem User]). You can then "Automatically move problem user messages
+to twit room" (answer Yes, then specify "Name of twit room" and remember
+to create that room). If you employ this logic, any user with level 2
+(Problem User) access will continue to have access to the same set of
+rooms, but all messages posted will automatically be routed to the
+Trashcan (or whatever you call your twit room).
+
+If you have the Internet mail gateway installed, you have the option of
+restricting its use on a user-by-user basis. If you wish to do this,
+answer Yes to "Restrict Internet mail to only those with that privilege."
+
+"Name of room to log pages" is where you can specify a room to which all
+pages (also called express messages or instant messages) will be logged.
+You may wish to do this for security reasons.
+
+
+ The next set of options deals with the tuning of your system. It is
+safe to leave these untouched.
+
+
+ Server connection idle timeout (in seconds) [900]:
+ Maximum concurrent sessions [20]:
+ Maximum message length [2147483647]:
+ Minimum number of worker threads [5]:
+ Maximum number of worker threads [256]:
+ Server-to-server networking password [xxxxx]:
+
+
+
+
+The "Server connection idle timeout" is for the connection between client
+and server software. It is not an idle timer for the user interface.
+900 seconds (15 minutes) is the default and a sane setting.
+
+"Maximum concurrent sessions" is the highest number of user sessions you
+wish to allow on your system at any given time. Citadel can scale to
+hundreds of concurrent users, but if you have limited hardware or (more
+likely) limited bandwidth, you might wish to set a maximum. You can also
+set it to zero for no limit.
+
+"Maximum message length" is just that. This could be a good way to
+prevent enormous multimedia files from finding their way into your
+message base.
+
+The minimum and maximum number of worker threads can be tuned to your
+liking. Citadel will attempt to keep one worker thread running per
+session, within these constraints. You should be aware that due to the
+use of the worker thread model, Citadel can handle a alarge number of
+concurrent sessions with a much smaller thread pool. If you don't know
+the programming theory behind multithreaded servers, you should leave
+these parameters alone.
+
+The "server-to-server networking password" may be set to some secret value
+to allow authenticated networking between Citadel servers.
+
+
+ The final set of options deals with the purging or expiry of old
+objects off the system, and the new smtp/pop settings.
+
+
+
+ POP3 server port (-1 to disable) [110]:
+ SMTP server port (-1 to disable) [25]:
+ Default user purge time (days) [61]:
+ Default room purge time (days) [21]:
+ System default message expire policy (? for list) [2]:
+ Keep how many messages online? [150]:
+ Save this configuration? Yes
+
+
+
+New settings to (.A)ide (S)ystem (G)eneral:
+
+POP/SMTP settings. Citadel is now capable of being it's own internet
+e-mail server (smtp) or pop server. If you want that functionality, enter
+in the correct ports. Normally this will be 110 for pop or 25 for smtp. More on this is in mailsetup.html.
+
+Any user who does not log in for the period specified in "Default user
+purge time" will be deleted the next time a purge is run. This setting
+may be modified on a per-user basis.
+
+"Default room purge time" behaves the same way, and may also be modified
+on a per-room basis.
+
+"System default message expire policy" defines the way in which old
+messages are expired (purged) off the system. You can specify any of:
+
+ Purge by age (specify in days)
+ Purge by message count in the room (specify number of messages)
+ Do not purge at all
+
+ Again, this setting may be overridden on a per-floor basis, and the
+floor setting may be overridden on a per-room basis.
+
+
+ When you're done, enter "Yes" to confirm the changes, or "No" to abort.
projects / citadel.git / commitdiff