From f8a7a76ab5e00b34eeff6e30f97b8fa215dc7008 Mon Sep 17 00:00:00 2001 From: Art Cancro Date: Sun, 9 Feb 2003 03:06:05 +0000 Subject: [PATCH] *** empty log message *** --- citadel/docs/install.txt | 412 --------------------------------------- 1 file changed, 412 deletions(-) delete mode 100644 citadel/docs/install.txt diff --git a/citadel/docs/install.txt b/citadel/docs/install.txt deleted file mode 100644 index 3af011b50..000000000 --- a/citadel/docs/install.txt +++ /dev/null @@ -1,412 +0,0 @@ - - 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 an ordinary Linux 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) - - Setup programs - - A 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 mandatory that the sysop have "root" access to the operating -system. The following are required to install Citadel/UX: - - - A Unix operating system (Linux, BSD, Solaris, Tru64, HP/UX) - - C compiler (such as gcc or egcs) and "make" - - POSIX threads (the "pthreads" library) - - TCP/IP - - Berkeley DB v3.1 or newer, or GDBM 1.8 or newer - - 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 run it on a recent distribution (such as Red Hat 7.0 or newer). A -new-ish distribution will have most or all of the prerequisite tools and -libraries already 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. - - - Access to Citadel via *any* standards-compliant e-mail program, thanks - to Citadel's built-in SMTP, POP, and IMAP services. - - 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 either Berkeley DB, or GDBM installed on your system, and -that you have all the development libraries and headers in place so that you -can compile against them. If you don't, you can get the latest Berkeley DB -at http://www.sleepycat.com *or* you can get GDBM from http://www.gnu.org or -one of its mirrors. We strongly recommend Berkeley DB for all but the lightest -of installations, as it is far more robust and reliable. - - If your operating system uses a separate library to support POSIX threads -(pthreads), 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. - - - BYPASSING THE login: PROMPT - - If you normally log in to your host system using some method other than -telnet (such as ssh), you might want the telnet service to go straight to -the Citadel BBS, instead of displaying the "login:" prompt first. You can -do this by having telnetd start citadel directly instead of /bin/login. - - An example for inetd: - - telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd -L /usr/local/citadel/citadel - - An example for xinetd: - - service telnet - { - flags = REUSE - socket_type = stream - wait = no - user = root - server = /usr/sbin/in.telnetd - server_args = -L /usr/local/citadel/citadel - log_on_failure += USERID - disable = no - } - - Please make sure you know what you're doing before you install this! - - - - 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. - - Mac OS X 10.1 and later are now supported. (Sorry, 10.0 cannot be -supported, now or in the future.) You need to install the Developer -Tools CD, which you can purchase or download for free from -http://developer.apple.com/ . Then run configure like this: - - env CC=/usr/bin/cc ./configure - - 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=/usr/local/citadel (or whatever) - - If you've got Berkeley DB installed in a non-standard location, you can -help the configure script find it by doing something like this: - - ./configure --with-db=/usr/local/BerkeleyDB-3.1 - - The configure script prefers Berkeley DB if it is available, but will fall -back to GDBM if it has to. - - 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. - - - UPGRADING - - Upgrading to a new version uses the same build procedure as compiling the -program for a fresh install, except that you want to do "make install-exec" -instead of "make install". This will overwrite the programs but not your -data. Be sure to shut down citserver during this process! - - - 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. - - - 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. (Note that this only applies to -GDBM installations; if you are using Berkeley DB it has no effect.) - - - 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. - - - WELCOMING NEW USERS - - Sometimes you might decide that you want a welcome message (or several -different messages) automatically mailed to new users upon their first login. -Now there is a way to do this. If you create a room called -"New User Greetings", and it is a *private* room (invitation-only probably -makes the most sense), any messages you enter into that room will automatically -be delivered to all new users upon registration. - - You can put anything you want there: a welcome message, system policies, -special information, etc. You can also put as many messages there as you -want to (although it really doesn't make sense to clutter new users' mailboxes -with lots of junk). - - Don't worry about wasting disk space, either. Citadel has a single-instance -message store, so all the new users are actually looking at the same copy of -the message on disk. - - - 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 someday. - - 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. - - - - - TROUBLESHOOTING AND GETTING HELP - - 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://uncensored.citadel.org - - 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 DO NOT e-mail the -developers directly. Post a request for help on the BBS, with 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 Berkeley DB or 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). -- 2.39.2