1 Citadel/UX Installation Procedure
2 See copyright.doc for copyright information
7 Citadel/UX is an advanced, multiuser, client/server, room-based BBS
8 program. It is designed to handle the needs of both small dialup systems and
9 large-scale Internet-connected systems. It was originally developed on an
10 Altos system running Xenix, and has been installed and tested on various
11 Unix and Unix-like platforms. The author's current development environment
12 (and BBS) is a Linux/GNU system. The current distribution includes:
14 - The Citadel/UX server (this is the back end that does all processing)
15 - A text-based client program designed with the traditional Citadel "look
16 and feel" (room prompts, dot commands, and the like)
17 - A networker that utilizes any file transfer mechanism (such as UUCP for
18 standalone systems, or ftp for Internet) and can share messages with other
19 Citadel/UX systems, as well as UseNet sites. Gateway software to talk
20 with C86NET (Citadel-86 and its deriviatives), HengeNet (StoneHenge),
21 and NYTI FordBoard is also available.
23 - A rich set of utilities for system administration and maintenance
26 Some knowledge of the Unix system is necessary to install and manage the
27 system. It is preferable that the sysop have superuser access to the operating
28 system. The following are required to install Citadel/UX:
30 - Some sort of Unix (or Unix look-alike) operating system
34 - the "make" utility (you don't want to try compiling it manually!)
35 - Enough disk space to hold all of the programs and data
40 - "WebCit", a gateway program to allow full access to Citadel/UX BBS's
41 via the World Wide Web. Interactive access through any Web browser.
43 - A point-and-click client program for MS Windows. (The text-based client
44 is now available for Windows as well.)
48 - A client program written in Java that will be portable to all operating
53 EVERYTHING IN ITS PLACE...
55 Hopefully you've unpacked the distribution archive into its own directory.
56 This is the directory in which all Citadel files are located and in which all
57 BBS activity will take place. Several subdirectories have already been created
58 during the unpacking process, and others may be created by the software if
64 There will be one account in /etc/passwd which all BBS users will use to
65 login to the system. This account is typically called "bbs" or "citadel" or
66 something to that effect. You will tell Citadel what the user-id of that
67 account is, and when someone logs in under that account, Citadel will prompt
70 The BBS login should have a unique uid. The home directory should be the
71 one your BBS resides in (in this example we will use /usr/bbs) and the shell
72 should be either "citadel" in that directory, or a script that will start up
73 citadel (you may wish to set up an external text editor; see below). Example:
75 bbs::100:1:BBS Login:/usr/citadel:/usr/citadel/citadel
77 When you run setup later, you will be required to tell it what the BBS
78 login's numeric user ID is, so it knows what user to run as.
80 For all other users in /etc/passwd, Citadel will automatically set up an
81 account using the "full name" field. No password is required, since it
82 assumes that if a user is logged in, he/she has already entered a password.
83 Note that this does have to be enabled at compile time (see ENABLE_AUTOLOGIN
84 in the Makefile). If such an account needs to be accessed remotely (such as
85 from client software), these users can use *either* their Citadel login name
86 or their login name on the host computer, and their password on the host
90 EDITING STUFF BEFORE COMPILING...
92 If you are upgrading an existing installation, be sure to check the
93 sysconfig.h header, to make sure the values there are the same as in your
94 previous installation. For a new system, it's best to leave these values
95 alone, so you won't have to worry about it the next time you upgrade.
97 You might also want to check the "Configure" script for platform-specific
98 stuff. Any platforms which have been tested will be auto-detected by the
99 script and the compiler and linker directives set accordingly. If your
100 platform isn't autodetected, you'll have to figure out the flags yourself (but
101 please get in touch so your platform can be supported in the next release!).
104 COMPILING THE PROGRAMS
107 As with most Unix programs, you compile it using these two commands:
112 The 'Configure' script will generate a Makefile from the Makefile.in, and
113 it will also write the file "sysdep.h" to your Citadel directory. Please do
114 not edit sysdep.h or Makefile.in yourself. The Configure script will figure
115 out your system dependencies and set everything correctly. The ONLY places
116 you should be editing, if anywhere at all, are sysconfig.h and Configure.
118 File permissions are always a bother to work with. You don't want the
119 board to crash because someone couldn't access a file, but you also don't
120 want shell users peeking into the binaries to do things like reading others'
121 mail, finding private rooms, etc. The Citadel server needs to be started
122 as root in order to bind to a privileged port, but as soon as its
123 initialization is finished, it changes its user ID to your BBS user ID in
124 order to avoid security holes.
129 This is a change from the way things were done before. All client-side setup
130 is in a "citadel.rc" file. The standard client looks for this file in:
132 2. /usr/local/lib/citadel.rc
133 3. <compiled BBSDIR>/citadel.rc
135 The next couple of sections deal with client-side configuration.
137 USING AN EXTERNAL EDITOR FOR MESSAGES
139 Citadel/UX has a built-in message editor. However, you can also use your
140 favorite text editor to write messages. To do this you simply put a line in
141 your citadel.rc file like:
145 ...would make Citadel call the vi editor when using the .<E>nter <E>ditor
146 command. You can also make it the default editor for the <E>nter command by
147 editing the citadel.rc file. (WARNING: external editors on public systems
148 can create a security hole. Make sure there is absolutely no way for users
149 to drop into the shell from the editor, or save files other than the temp file
152 Using this mechanism, shell users can pick their favorite editor for Citadel.
153 BBS users can use external editors too; just have the bbs login call a script
154 that sets the variables and then calls citadel. I used to recommend using
155 an external editor as the default, but the built-in editor is now a bit more
156 robust, so the use of an external editor is definitely optional. By the
157 way, be VERY careful what editor you choose and how you set up its options.
158 Giving the general public to an editor like vi or emacs can open up lots of
161 Citadel runs the external editor using the REAL uid and gid of the user, if
162 you are running it in setuid mode.
167 Citadel/UX can send messages to a printer, or just about anywhere else in
168 your system. The variable PRINTCMD in citadel.rc specifies what command you
169 use to print. Text is sent to the standard input (stdin) of the print command.
173 printcmd="nl|pr|lpr -dlocal"
175 ...that would add line numbers, then paginate, then print on the printer
176 named "local". There's tons of stuff you can do with this feature. For
177 example, you could use a command like "cat >>$HOME/archive" to save copies
178 of important messages in a textfile.
183 Before logging in for the first time, you must run the setup program. Type
184 "./setup" to begin this procedure. (Be sure to use the "./" because some
185 systems, most notably the Slackware distribution of Linux, will run the
186 operating system's own setup program if you just type the word "setup".)
187 Sit back and relax; there are a slew of options here that will allow you to
188 customize the BBS to your liking.
190 The setup program will ask you what directory to place your data files in.
191 You can use this functionality to keep your programs and data in different
192 directories, or to run more than one BBS on the same computer. If you don't
193 use the default directory (the one specified in the Makefile), remember to
194 specify the directory name again when you start up the server later on.
196 If this is a new installation, the setup program will automatically
197 create all of your data files. Otherwise, it will ask you if you want to
198 re-initialize them. Normally you will answer "no" unless you want to wipe
199 out your system for some reason.
202 PREPARING TO START THE SERVER
204 Before you can use Citadel, you must define the "citadel" service to your
205 system. This is accomplished by adding a line to your /etc/services file that
206 looks something like this:
208 citadel 504/tcp # Citadel/UX Server
210 504 is the port number officially designated by the IANA for use by Citadel.
211 There should not be any need to use a different port number, unless you are
212 running multiple BBS's on the same computer and therefore need a different
215 The next step is to arrange for the server to start. The "citserver"
216 program is the main Citadel server. Before we cover the recommended method of
217 starting the server, let's examine its usage options:
219 citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-d]
221 The options are as follows:
223 -hHomeDir - the directory your BBS data files live in. This should, of
224 course, be a directory that you've run the "setup" program against to set up
225 some data files. If a directory is not specified, the directory name which
226 was specified in the Makefile will be used.
228 -xDebugLevel - Set the verbosity of trace messages printed. The available
229 debugging levels are:
230 1 - Internal errors (failed thread creation, malloc problems, etc.)
231 2 - Network errors (broken sockets, failed socket creation)
232 3 - Begin and end of sessions, startup/shutdown of server
233 5 - Server commands being sent from clients
234 7 - Entry and exit of various functions
235 8 - Entry and exit of critical sections
236 9 - Various debugging checkpoints (insanely verbose)
238 -tTraceFile - Tell the server where to send its debug/trace output.
239 Normally it is sent to stdout.
241 -d - Run as a daemon. This switch would be necessary if you were
242 starting the Citadel server, for example, from an rc.local script (which is
246 The preferred method of starting the Citadel server is to place an entry in
247 your /etc/inittab file. This will conveniently bring the server up when your
248 system is up, and terminate it gracefully when your system is shutting down.
249 The exact syntax for your system may vary, but here's the entry that I use on
252 cit:2345:respawn:/appl/citadel/citserver -h/appl/citadel -t/dev/tty6 -x3
254 What I've done here is to set debugging level 3, and have the trace stuff
255 output to one of my virtual consoles. It's important to remember to turn off
256 any getty that is set up on that virtual console, if you do this. After
257 making this change, the command "init q" works on most systems to tell init
258 to re-read the file. If in doubt, just reboot your computer.
261 LOGGING IN FOR THE FIRST TIME
263 At this point, your system is ready to run. Run the citadel program from
264 the shell and it will automatically create your account. NOTE: the first
265 user account to be created will automatically be set to access level 6
266 (Aide). This overcomes some obvious logistical problems - normally, Aide
267 access is given by another Aide, but since there aren't any on your system
268 yet, this isn't possible. You could also use the useradmin utility to
269 accomplish the same thing, but this makes it a bit easier.
272 SPACE FOR ADDING YOUR OWN FEATURES (doors)
274 The "doorway" feature is just a generic way to add features to the system.
275 I called it "Doorway" to make it resemble the doors on non-Unix boards, but as
276 we all know, us Unix types don't have to write special code to access the
277 modem. :-) Anyway, when a user hits the <*> (doorway) command, Citadel does...
279 USERNAME=<username>; export USERNAME
280 ./subsystem <user number> <screen width> <access level>
282 ...so you can put whatever you want in there. I suggest putting in a menu
283 program to allow the users to pick one of a number of programs, etc.
285 Do be aware that chat and door programs will only be available when two
288 1. The client and server programs are running on the same computer
289 2. The user is running the text-based Unix client.
291 Because of these restrictions, Door programs are being utilized less and
296 SETTING UP CITADEL TO SEND AND RECEIVE INTERNET MAIL
298 Mail programs are now elaborate enough that it is trivial to set up Citadel
299 to act as your system's local mail delivery agent. It couples easily with
300 either sendmail or smail, or with any other mail system that is capable of
301 invoking a separate program to deliver local mail.
303 Unlike earlier versions of Citadel/UX, there is no longer a need to play
304 with rmail or to patch other pieces of your system's existing mailer. Simply
305 make a few quick configurations, compile the Citadel/UX package "as is, and
306 you're ready to go. Here's how to do it:
308 1. First, open up the config file "internetmail.config" in the "network"
309 directory, and edit the definitions in it to your local configuration. It's
310 very self-documented; just go through the file making any necessary changes.
312 2. Next, you must configure your system's main mail delivery agent to
313 use the "citmail" program to deliver mail to local addresses. This will
314 change from mailer to mailer, of course. I'm using sendmail, and although
315 I don't know enough about sendmail to provide really good instructions on
316 sendmail configuration, here's what worked for me:
318 I added the following mailer definition:
320 Mcitadel, P=/appl/citadel/citmail, F=lsDFMoqeu9, S=10/30, R=20/40, D=$z:/,
322 A=/appl/citadel/citmail $u
324 Then I replaced all instances of "#local" with "#citadel". This seems to
325 work on my system; your mileage may vary.
327 3. Some mailers will need to be killed and restarted for the changes to
328 take effect. Once this is done, all of your BBS users now have an Internet
329 e-mail address. They can use two forms of addresses:
331 user_name@your.system.name
332 cit1234@your.system.name
334 In the first form, the name portion of the user's Internet e-mail address
335 is the name they use on your Citadel system, with all spaces replaced by
336 underscores. In the second form, the name is the letters "cit" followed
337 by the user's user number. This is a nice shorthand that is sometimes
338 easier to use. Note that the help file <.H>elp MAIL is set up to tell users
339 what their address is.
341 NOTE: I cannot and will not answer e-mails regarding the configuration of
342 sendmail or any other mailer. I am not a sendmail expert; what is written
343 above is everything I know about getting Citadel and sendmail to talk to each
344 other. Please refer these questions to your local sendmail wizard.
350 That's just about all the information you need to install the system. If
351 you have any comments, suggestions, bomb threats, etc., send them to
352 ajc@uncnsrd.mt-kisco.ny.us or call Uncensored Communications Group BBS at
353 (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).