2 Citadel/UX Installation Procedure
3 See copyright.txt for copyright information
8 Citadel/UX is an advanced, multiuser, client/server, room-based BBS
9 program. It is designed to handle the needs of both small dialup systems and
10 large-scale Internet-connected systems. It was originally developed on an
11 Altos system running Xenix, and has been installed and tested on various
12 Unix and Unix-like platforms. The author's current development environment
13 (and BBS) is a Linux/GNU system. The current distribution includes:
15 - The Citadel/UX server (this is the back end that does all processing)
16 - A text-based client program designed with the traditional Citadel "look
17 and feel" (room prompts, dot commands, and the like)
18 - A networker that can share rooms and email between multiple systems.
19 Replication can be performed via TCP/IP or any external transport.
21 - A rich set of utilities for system administration and maintenance
24 Some knowledge of the Unix system is necessary to install and manage the
25 system. It is mandatory that the sysop have "root" access to the operating
26 system. The following are required to install Citadel/UX:
28 - A Unix operating system (Linux, BSD, Solaris, Tru64, HP/UX)
29 - C compiler (such as gcc or egcs) and "make"
30 - POSIX threads (the "pthreads" library)
32 - Berkeley DB v3.1 or newer, or GDBM 1.8 or newer
33 - Enough disk space to hold all of the programs and data
35 If you are running Citadel/UX on a Linux system, it is STRONGLY recommended
36 that you run it on a recent distribution (such as Red Hat 7.0 or newer). A
37 new-ish distribution will have most or all of the prerequisite tools and
38 libraries already integrated for you.
43 - "WebCit", a gateway program to allow full access to Citadel/UX BBS's
44 via the World Wide Web. Interactive access through any Web browser.
48 - Newer and better GUI based clients.
52 EVERYTHING IN ITS PLACE...
54 Hopefully you've unpacked the distribution archive into its own directory.
55 This is the directory in which all Citadel files are located and in which all
56 BBS activity will take place. Several subdirectories have already been created
57 during the unpacking process, and others may be created by the software if
60 Make sure you have either Berkeley DB, or GDBM installed on your system, and
61 that you have all the development libraries and headers in place so that you
62 can compile against them. If you don't, you can get the latest Berkeley DB
63 at http://www.sleepycat.com *or* you can get GDBM from http://www.gnu.org or
64 one of its mirrors. We strongly recommend Berkeley DB for all but the lightest
65 of installations, as it is far more robust and reliable.
67 If your operating system uses a separate library to support POSIX threads
68 (pthreads), make sure that library is installed as well.
73 There will be one account in /etc/passwd which all BBS users will use to
74 login to the system. This account is typically called "bbs" or "citadel" or
75 something to that effect. You will tell Citadel what the user-id of that
76 account is, and when someone logs in under that account, Citadel will prompt
79 The BBS login should have a unique uid. The home directory should be the
80 one your BBS resides in (in this example we will use /usr/citadel) and the
81 shell should be either "citadel" in that directory, or a script that will start
82 up citadel (you may wish to set up an external text editor; see below).
85 bbs::100:1:BBS Login:/usr/citadel:/usr/citadel/citadel
87 When you run setup later, you will be required to tell it what the BBS
88 login's numeric user ID is, so it knows what user to run as. If you create
89 an account called bbs, guest, or citadel, the setup program will automatically
90 pick up the user ID by default.
92 For all other users in /etc/passwd, Citadel will automatically set up an
93 account using the "full name" field. No password is required, since it
94 assumes that if a user is logged in, he/she has already entered a password.
95 Note that this does have to be enabled at compile time (see ENABLE_AUTOLOGIN
96 in the Makefile). If such an account needs to be accessed remotely (such as
97 from client software), these users can use *either* their Citadel login name
98 or their login name on the host computer, and their password on the host
102 BYPASSING THE login: PROMPT
104 If you normally log in to your host system using some method other than
105 telnet (such as ssh), you might want the telnet service to go straight to
106 the Citadel BBS, instead of displaying the "login:" prompt first. You can
107 do this using the "loginwrapper.sh" wrapper program.
109 telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd -L /usr/local/citadel/loginwrapper.sh
111 Please make sure you know what you're doing before you install this!
115 COMPILING THE PROGRAMS
118 You can easily compile Citadel with the following commands:
124 The 'configure' script will generate a Makefile from the Makefile.in, and
125 it will also write the file "sysdep.h" to your Citadel directory. Please do
126 not edit sysdep.h or Makefile.in yourself. The configure script will figure
127 out your system dependencies and set everything correctly.
129 By default, the Citadel system will install in /usr/local/citadel. If you
130 wish to place it in a different directory, you can instead do:
132 ./configure --prefix=/usr/local/citadel (or whatever)
134 If you've got Berkeley DB installed in a non-standard location, you can
135 help the configure script find it by doing something like this:
137 ./configure --with-db=/usr/local/BerkeleyDB-3.1
139 The configure script prefers Berkeley DB if it is available, but will fall
140 back to GDBM if it has to.
142 File permissions are always a bother to work with. You don't want the
143 board to crash because someone couldn't access a file, but you also don't
144 want shell users peeking into the binaries to do things like reading others'
145 mail, finding private rooms, etc. The Citadel server needs to be started
146 as root in order to bind to a privileged port, but as soon as its
147 initialization is finished, it changes its user ID to your BBS user ID in
148 order to avoid security holes.
153 Upgrading to a new version uses the same build procedure as compiling the
154 program for a fresh install, except that you want to do "make install-exec"
155 instead of "make install". This will overwrite the programs but not your
156 data. Be sure to shut down citserver during this process!
161 This is a change from the way things were done before. All client-side setup
162 is in a "citadel.rc" file. The standard client looks for this file in:
164 2. /usr/local/lib/citadel.rc
165 3. <compiled BBSDIR>/citadel.rc
167 The next couple of sections deal with client-side configuration.
169 USING AN EXTERNAL EDITOR FOR MESSAGES
171 Citadel/UX has a built-in message editor. However, you can also use your
172 favorite text editor to write messages. To do this you simply put a line in
173 your citadel.rc file like:
177 ...would make Citadel call the vi editor when using the .<E>nter <E>ditor
178 command. You can also make it the default editor for the <E>nter command by
179 editing the citadel.rc file. (WARNING: external editors on public systems
180 can create a security hole. Make sure there is absolutely no way for users
181 to drop into the shell from the editor, or save files other than the temp file
184 Using this mechanism, shell users can pick their favorite editor for Citadel.
185 BBS users can use external editors too; just have the bbs login call a script
186 that sets the variables and then calls citadel. I used to recommend using
187 an external editor as the default, but the built-in editor is now a bit more
188 robust, so the use of an external editor is definitely optional. By the
189 way, be VERY careful what editor you choose and how you set up its options.
190 Giving the general public to an editor like vi or emacs can open up lots of
196 Citadel/UX can send messages to a printer, or just about anywhere else in
197 your system. The variable PRINTCMD in citadel.rc specifies what command you
198 use to print. Text is sent to the standard input (stdin) of the print command.
202 printcmd="nl|pr|lpr -dlocal"
204 ...that would add line numbers, then paginate, then print on the printer
205 named "local". There's tons of stuff you can do with this feature. For
206 example, you could use a command like "cat >>$HOME/archive" to save copies
207 of important messages in a textfile.
212 urlcmd=netscape -remote "openURL(%s)"
214 ...that would mean that typing 'u' in a room prompt after seeing a url in
215 one of the room's messages netscape will open up for you and run that url.
219 Before logging in for the first time, you must run the setup program. Type
220 "./setup" to begin this procedure.
222 The setup program will ask you what directory to place your data files in.
223 You can use this functionality to keep your programs and data in different
224 directories, or to run more than one BBS on the same computer. If you don't
225 use the default directory (the one specified in the Makefile), remember to
226 specify the directory name again when you start up the server later on.
228 If you've used older versions of Citadel/UX before, you'll notice that the
229 setup program does much less than it did before. It won't create any empty
230 data files; that's now done automatically by the server the first time it
231 starts. It also asks only a few questions; that's because the rest of the
232 global configuration is now done from within Citadel.
235 PREPARING TO START THE SERVER
237 The files /etc/services and /etc/inittab must be modified in order to run
238 the Citadel server. The setup program will perform the correct modifications
239 for you if you allow it to. If you'd prefer to do it manually, or if you're
240 interested in what these modifications are, then read on...
242 Before you can use Citadel, you must define the "citadel" service to your
243 system. This is accomplished by adding a line to your /etc/services file that
244 looks something like this:
246 citadel 504/tcp # Citadel/UX Server
248 504 is the port number officially designated by the IANA for use by Citadel.
249 There should not be any need to use a different port number, unless you are
250 running multiple BBS's on the same computer and therefore need a different
253 The next step is to arrange for the server to start. The "citserver"
254 program is the main Citadel server. Before we cover the recommended method of
255 starting the server, let's examine its usage options:
257 citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-d] [-f]
259 The options are as follows:
261 -hHomeDir - the directory your BBS data files live in. This should, of
262 course, be a directory that you've run the "setup" program against to set up
263 some data files. If a directory is not specified, the directory name which
264 was specified in the Makefile will be used.
266 -xDebugLevel - Set the verbosity of trace messages printed. The available
267 debugging levels are:
268 1 - Internal errors (failed thread creation, malloc problems, etc.)
269 2 - Network errors (broken sockets, failed socket creation)
270 3 - Begin and end of sessions, startup/shutdown of server
271 5 - Server commands being sent from clients
272 7 - Entry and exit of various functions
273 8 - Entry and exit of critical sections
274 9 - Various debugging checkpoints (insanely verbose)
276 -tTraceFile - Tell the server where to send its debug/trace output.
277 Normally it is sent to stdout.
279 -d - Run as a daemon. This switch would be necessary if you were
280 starting the Citadel server, for example, from an rc.local script (which is
281 not recommended, because this won't allow the server to automatically restart
282 when it is shut down).
284 -f - Defragment all the databases upon startup. This isn't
285 normally necessary due to the nature of the data stored in Citadel, but the
286 option is provided in case you need it. (Note that this only applies to
287 GDBM installations; if you are using Berkeley DB it has no effect.)
290 The preferred method of starting the Citadel server is to place an entry in
291 your /etc/inittab file. This will conveniently bring the server up when your
292 system is up, and terminate it gracefully when your system is shutting down.
293 The exact syntax for your system may vary, but here's the entry that I use on
296 cit:2345:respawn:/appl/citadel/citserver -h/appl/citadel -t/dev/tty6 -x3
298 What I've done here is to set debugging level 3, and have the trace stuff
299 output to one of my virtual consoles. It's important to remember to turn off
300 any getty that is set up on that virtual console, if you do this. After
301 making this change, the command "init q" works on most systems to tell init
302 to re-read the file. If in doubt, just reboot your computer.
305 LOGGING IN FOR THE FIRST TIME
307 At this point, your system is ready to run. Run the citadel program from
308 the shell and it will automatically create your account. NOTE: the first
309 user account to be created will automatically be set to access level 6
310 (Aide). This overcomes some obvious logistical problems - normally, Aide
311 access is given by another Aide, but since there aren't any on your system
312 yet, this isn't possible.
315 SPACE FOR ADDING YOUR OWN FEATURES (doors)
317 *** PLEASE TAKE NOTE!! *** This function really represents the "old"
318 way of doing things, and it doesn't fit in well with the client/server
319 paradigm. Please consider it "deprecated" because it may be removed someday.
321 The "doorway" feature is just a generic way to add features to the system.
322 I called it "Doorway" to make it resemble the doors on non-Unix boards, but as
323 we all know, us Unix types don't have to write special code to access the
324 modem. :-) Anyway, when a user hits the <*> (doorway) command, Citadel does...
326 USERNAME=<username>; export USERNAME
327 ./subsystem <user number> <screen width> <access level>
329 ...so you can put whatever you want in there. I suggest putting in a menu
330 program to allow the users to pick one of a number of programs, etc.
332 Do be aware that chat and door programs will only be available when two
335 1. The client and server programs are running on the same computer
336 2. The user is running the text-based Unix client.
338 Because of these restrictions, Door programs are being utilized less and
344 TROUBLESHOOTING AND GETTING HELP
346 That's just about all the information you need to install the system.
347 For more information, visit the Citadel/UX web site at UNCENSORED! BBS,
348 http://uncensored.citadel.org
350 Please note: if you intend to report a problem getting the Citadel server
351 to run, please first check the following:
353 1. Did you do ./configure && make && make install ??
354 2. Did you run setup?
355 3. Did you start the server?
357 To report a problem, you can log on to UNCENSORED! or any other BBS on the
358 Citadel network which carries the Citadel/UX> room. Please DO NOT e-mail the
359 developers directly. Post a request for help on the BBS, with all of the
360 following information:
362 1. The exact nature of your difficulty
363 2. A transcript of the error message(s) if possible
364 3. The version of Citadel you are running
365 4. The version of Berkeley DB or GDBM present on your system
366 5. Which operating system you are running, and what version
367 6. If you are running a Linux system, we need to know which distribution, and
368 the version of the kernel, libc, and pthreads you are using (it would help to
369 post the output of a "ldd ./citserver" command).