Citadel/UX Installation Procedure See copyright.doc 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 utilizes any file transfer mechanism (such as UUCP for standalone systems, or ftp for Internet) and can share messages with other Citadel/UX systems, as well as UseNet sites. Gateway software to talk with C86NET (Citadel-86 and its deriviatives), HengeNet (StoneHenge), and NYTI FordBoard is also available. - 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: - Some sort of Unix (or Unix look-alike) operating system - C compiler - POSIX threads - TCP/IP - the "make" utility (you don't want to try compiling it manually!) - Enough disk space to hold all of the programs and data - A record manager or database capable of handling binary large objects (blobs). The current distribution is designed to work with the free GDBM record manager; however, modifying it to work with others should be straightforward. 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. - A point-and-click client program for MS Windows. (The text-based client is now available for Windows as well.) COMING SOON: - A client program written in Java that will be portable to all operating systems. 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. 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/bbs) 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. 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. EDITING STUFF BEFORE COMPILING... If you are upgrading an existing installation, be sure to check the sysconfig.h header, to make sure the values there are the same as in your previous installation. For a new system, it's best to leave these values alone, so you won't have to worry about it the next time you upgrade. You might also want to check the "Configure" script for platform-specific stuff. Any platforms which have been tested will be auto-detected by the script and the compiler and linker directives set accordingly. If your platform isn't autodetected, you'll have to figure out the flags yourself (but please get in touch so your platform can be supported in the next release!). COMPILING THE PROGRAMS As with most Unix programs, you compile it using these two commands: ./Configure make 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. The ONLY places you should be editing, if anywhere at all, are sysconfig.h and Configure. 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. /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 .nter ditor command. You can also make it the default editor for the 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. Citadel runs the external editor using the REAL uid and gid of the user, if you are running it in setuid mode. 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. SETUP AND LOGIN Before logging in for the first time, you must run the setup program. Type "./setup" to begin this procedure. (Be sure to use the "./" because some systems, most notably the Slackware distribution of Linux, will run the operating system's own setup program if you just type the word "setup".) Sit back and relax; there are a slew of options here that will allow you to customize the BBS to your liking. 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. Unlike in previous versions of Citadel/UX, the setup program is no longer responsible for creating empty data files. This is now done automatically by the server the first time it is started. PREPARING TO START THE SERVER 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] 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). 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. You could also use the useradmin utility to accomplish the same thing, but this makes it a bit easier. 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=; export USERNAME ./subsystem ...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. SETTING UP CITADEL TO SEND AND RECEIVE INTERNET MAIL Mail programs are now elaborate enough that it is trivial to set up Citadel to act as your system's local mail delivery agent. It couples easily with either sendmail or qmail, or with any other mail system that is capable of invoking a separate program to deliver local mail. Unlike earlier versions of Citadel/UX, there is no longer a need to play with rmail or to patch other pieces of your system's existing mailer. Simply make a few quick configurations, compile the Citadel/UX package "as is" and you're ready to go. Here's how to do it: 1. First, open up the config file "internetmail.config" in the "network" directory, and edit the definitions in it to your local configuration. It's very self-documented; just go through the file making any necessary changes. 2. Next, you must configure your system's main mail delivery agent to use the "citmail" program to deliver mail to local addresses. This will change from mailer to mailer, of course. I'm using sendmail, and although I don't know enough about sendmail to provide really good instructions on sendmail configuration, here's what worked for me: I added the following mailer definition: Mcitadel, P=/appl/citadel/citmail, F=lsDFMoqeu9, S=10/30, R=20/40, D=$z:/, T=X-Unix, A=/appl/citadel/citmail $u Then I replaced all instances of "#local" with "#citadel". This seems to work on my system; your mileage may vary. 3. Some mailers will need to be killed and restarted for the changes to take effect. Once this is done, all of your BBS users now have an Internet e-mail address. They can use two forms of addresses: user_name@your.system.name cit1234@your.system.name In the first form, the name portion of the user's Internet e-mail address is the name they use on your Citadel system, with all spaces replaced by underscores. In the second form, the name is the letters "cit" followed by the user's user number. This is a nice shorthand that is sometimes easier to use. Note that the help file <.H>elp MAIL is set up to tell users what their address is. NOTE: I cannot and will not answer e-mails regarding the configuration of sendmail or any other mailer. I am not a sendmail expert; what is written above is everything I know about getting Citadel and sendmail to talk to each other. Please refer these questions to your local sendmail wizard. THE PEANUT GALLERY That's just about all the information you need to install the system. If you have any comments, suggestions, bomb threats, etc., send them to ajc@uncnsrd.mt-kisco.ny.us or call Uncensored Communications Group BBS at (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).