@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: fifteen.tex,v 2.3 91/09/01 23:04:23 royce Exp $

@node Fifteen Minute Guide, Sysop Theory, Introduction, Top
@chapter The Fifteen Minute Guide to Fnordadel
@cindex Quick-start guide
@cindex Fifteen minute guide
@cindex Setup

This chapter provides quick and (we hope) easy instructions on how to get
your @sc{bbs} up and running.  We recommend that you also read, at least,
@ref{Sysop Theory}, so you know what's what, and whichever other
parts of the manual tickle your curiosity.

@node Initial Preparations, Configuration, Fifteen Minute Guide, Fifteen Minute Guide
@section Initial Preparations

In order for Fnordadel to run at all, you need to have the following:

@itemize @bullet
@item
An Atari ST or TT series computer with at least 512K of @sc{ram} and at least
one 360K disk drive.  More of both @sc{ram} and disk space always helps; in
particular, a hard disk is real nice.
@item
An RS-232 modem and cable.  The modem must be able to autoanswer.  Most
modems are Hayes-compatible; if yours is, it should work with Fnordadel.
@item
A text editor or word processor which reads and writes plain @sc{ascii}
files.  Any text editor will work, and most word processors will work if you
turn off ``WP mode'' or whatever they happen to call it.  Check your word
processor's manual.
@item
Optionally, some sort of shell or @sc{cli} (``command line interpreter'').  The
Fnordadel programs work by taking arguments on the command line which are
clumsy to specify using the @sc{gem} desktop; additionally, some features
of Fnordadel, like events, are unavailable or nearly useless unless you
use a shell.
@end itemize

@node Disk layout, Hard disk systems, Initial Preparations, Initial Preparations
@subsection Disk layout
@cindex Disk layout

The first thing you should do is to
set aside space on your storage devices to hold the Fnordadel binaries, the
online help files, and the data files comprising your @sc{bbs}.
How you do this will depend on how large you want your @sc{bbs} to be, and what
storage devices you have.  Fnordadel's space requirements are roughly
detailed below:

@itemize @bullet
@item
@pindex citadel
@pindex configur
The two essential binaries, @code{citadel} and @code{configur}, take around
210K.
@item
The help files consume about 110K of disk space.
@item
The userlog takes approximately 512 bytes (i.e., 0.5K) per user.  For a decent
sized log of around 100 users, allow 50K.
@item
The room files take at least 1K per room.  Allow about 60K for a set of 40
rooms.
@item
Other miscellaneous system files, including @file{ctdlcnfg.sys} (the
configuration file), the floors, net and other files can be expected to take
about another 50K.
@item
And finally, the message base takes exactly as much space as you allocate to
it.  For a reasonably busy system and allowing for old messages to be around
for about a week, you'd like around a 300K message base.  This is enough for
about 1000 average-sized messages.
@end itemize

With the preceeding in mind, here are a couple of suggestions for various
setups.

@node Hard disk systems, Floppy disk only systems, Disk layout, Initial Preparations
@subheading Hard disk systems
@cindex Hard disks

If you have a hard disk, things are relatively easy.  Here's one way
of doing it.
@itemize @bullet
@item
Make a directory someplace on your hard disk to hold
Fnordadel and your @sc{bbs}.  We recommend something close to the root of the
drive, since all pathnames will have to be specified relative to the root
directory, and you don't want to type
@samp{d:\foobar\bletch\blort\weevil\bbs\@dots{}} all the time.
So pick @samp{d:\bbs}, say.  
@item
Make a directory under @file{d:\bbs} called @samp{bin}, and put all of
the Fnoradel binaries in it.
@item
Copy the file @file{ctdlcnfg.doc} from the Fnordadel distribution into
@file{d:\bbs}.
@item
Make another directory under @file{d:\bbs}, calling this one @samp{help},
and copy all of the Fnordadel online help files into it.
@end itemize
@noindent
Also, if you do not already use a disk cacheing program you may want to
get one, as they can greatly improve disk performance.  Try `dcache'
or `Cold Hard Cache'.  If you have a hard drive based on an ICD host
adaptor, use the cache built into the ICD software.

@node Floppy disk only systems, Other details, Hard disk systems, Initial Preparations
@subheading Floppy disk only systems
@cindex Floppy disks

If you have only floppy disks, you'll need to plan things a bit more carefully.
You will probably want to use some
kind of @sc{ram}disk to hold parts of your system; not only does this increase the
amount of space you have online, but it speeds things up considerably as well.
There are thousands of @sc{ram}disk programs available for the ST.  We supply
one called Flashdisk which seems to work well; see the accompanying
documentation.  You will probably also want to format your @sc{bbs} disks
using an extended formatter of some kind, to increase your available storage
capacity.  We recommend DC Format.

A decent Fnordadel system will fit on one double-sided (i.e., 720K) disk,
although things will be a little cramped.  If you have two double-sided drives,
you're laughing---just put your @file{auto} folder, the Fnordadel binaries
and help files, @file{ctdlcnfg.sys}, and whatever other utility things you
need on the first disk (in drive A),
and put all the data files for your @sc{bbs} on the second disk (in drive B).
Paths to Fnordadel data files should begin with @samp{B:\@dots{}}.  You may
optionally run things with some or all of the data files from drive B living
in a @sc{ram}disk instead; you might want to configure the @sc{ram}disk program so that
at boot time it copies all necessary files from drive B into the @sc{ram}disk.

If you have only single-sided drives,
you'll need to split the files over two disks.  If you have only one
single-sided drive, you're still in the Stone Age---but yes, you can still
run Fnordadel.  Here's one suggested way:

Drive A: will contain:
@itemize @bullet
@item
@file{citadel.tos}
@item
the @file{help} directory
@item
a directory called @file{audit}
@item
@file{configur.tos}
@item
@file{ctdlcnfg.sys}
@item
a small text editor or word-processing program
@end itemize
You will also want to create a @sc{ram}disk of as large a size as possible; if you
have a 512K machine, you're limited to about a 200K @sc{ram}disk, while if you have
a 1Mb machine, you can use a @sc{ram}disk of up to 700--750K.
You'll set the data file paths so that after you run @code{configur}
(@pxref{Running configur}), the @sc{ram}disk will
contain:
@table @file
@item ctdlmsg.sys
the message base
@item room@var{nnnn}.sys
the room files; you specify how many in @file{ctdlcnfg.sys}
@item ctdlflr.sys
the floors file
@item ctdllog.sys
the user log file
@end table
You would then copy these files (which are empty to begin with) onto another
floppy, so that you have a physical backup version of them.

@node Other details,  , Floppy disk only systems, Initial Preparations
@subsection Other details

There are a few other things which you may need to attend to before you can
configure your system.  In no particular order:

@itemize @bullet
@item
If you're going to be using the @sc{gem} desktop, you will have to rename
most of the Fnordadel binaries from @file{.tos} to @file{.ttp} extensions.
This is because most of them take arguments (parameters) on the command line,
and you need to give them @file{.ttp} extensions to force @sc{gem} to pop
up the parameters dialog box.
@item
If you have a hard disk or you have @sc{tos} 1.4 or higher,
you should ensure that you have @code{foldr100} in
your @file{auto} folder, or that you have some other form of workaround for
the @sc{tos} 40-folder bug.  (If you have an @sc{ste}, you have @sc{tos} 1.6,
to which this item applies.)
@item
If you have @sc{tos} 1.4 or greater, you should have @code{poolfix} in your
@file{auto} folder.
@end itemize

@node Configuration, Bringing Up The System, Initial Preparations, Fifteen Minute Guide
@section Configuration
@cindex Initial configuration
@cindex Configuration

Briefly, here's how configuration goes.  First, you edit @file{ctdlcnfg.sys}
to customize your system.  Then you run @code{configur}, which digests
@pindex configur
@file{ctdlcnfg.sys} and creates all of the needed files and directories.
Simple, eh?

@node Editing ctdlcnfg.sys, Running configur, Configuration, Configuration
@subsection Editing ctdlcnfg.sys

The base Fnordadel configuration file is supplied to you as
@file{ctdlcnfg.doc}.  It is exhaustively commented, so we recommend that you
read it from start to finish, changing the parameters as you go.  When you're
done, save it as @file{ctdlcnfg.sys}.  After doing so you may wish
to move the original @file{ctdlcnfg.doc} off of your working disks if you're
short of space; you might also want to remove the comments from @file{ctdlcnfg.sys}.

The following sections give you a few insights into which parameters you
should set and how.

@node General parameters, Modem parameters, Editing ctdlcnfg.sys, Editing ctdlcnfg.sys
@subsubsection General parameters

The following general parameters should all be altered
by you.  If you don't, some won't make any sense on your @sc{bbs},
while others will make the configuration program crap out as
it tries to do its thing.  Read the parameter descriptions in
@file{ctdlcnfg.doc}.  Here's the list:
@vindex nodetitle
@vindex nodename
@vindex nodeid
@vindex organization
@vindex domain
@vindex baseroom
@vindex basefloor
@vindex syspassword
@vindex sysop
@vindex logsize
@vindex messagek
@vindex cryptseed
@vindex maxrooms
@vindex mailslots
@vindex sharedrooms
@vindex msgdir
@vindex sysdir
@vindex roomdir
@vindex helpdir
@vindex auditdir
@vindex netdir
@example
Misc.           Sizes and such          Directories
---------------------------------------------------
#nodetitle      #define logsize         #msgdir
#nodename       #define messagek        #sysdir
#nodeid         #define cryptseed       #roomdir
#organization   #define maxrooms        #helpdir
#domain         #define mailslots       #auditdir
#baseroom       #define sharedrooms     #netdir
#basefloor
#syspassword
#sysop
@end example
With the various directories, you might wish to combine
one or more of them together, especially if you're running on
floppy disk drives or @sc{ram}disk.  In that case, just define the
various directory parameters to the same value.

@node Modem parameters, Networking parameters, General parameters, Editing ctdlcnfg.sys
@subsubsection Modem parameters

The following parameters are all modem-related.  If
you have a Hayes-compatible modem, you'll have to change very
few of the parameters.  If your modem is not a Hayes-compatible
but is still driven by software commands of some
kind, you still might be able to get it working.  If you have
to do anything that you think is unusual to make your modem
work, let the Fnordadel team know so they can pass the info
along to others.  Here's the list of parameters to look at:
@vindex calloutprefix
@vindex calloutsuffix
@vindex sysbaud
@vindex init-speed
@vindex modemsetup
@vindex hayes
@vindex reply300
@vindex reply1200
@vindex reply2400
@vindex reply9600
@vindex reply19200
@example
Misc.                   Connect reply messages
----------------------------------------------
#calloutprefix          #reply300
#calloutsuffix          #reply1200
#define sysbaud         #reply2400
#define init-speed      #reply9600
#modemsetup             #reply19200
#define hayes
@end example
With the modem reply messages, you'll probably want
to comment out the ones that don't apply to your modem, e.g.
@vindex reply19200
@code{#reply19200}, or else set them to the empty string @samp{""}.  Other
general tips are that the modem must report the true state of
the DCD and DTR signals, and should be set to have command
echoing off and numeric result codes.  For more details, see @ref{Modem Stuff}.

@node Networking parameters,  , Modem parameters, Editing ctdlcnfg.sys
@subsubsection Networking parameters

For this first pass through the configuration, our recommendation is that
you pretty much ignore networking.  However, you should comment out the
following items in @file{ctdlcnfg.doc} (by placing a @samp{*} at the
beginning of the line) to avoid possible glitches.
@vindex event
@vindex polling
@vindex poll-delay
@example
#event NETWORK
#polling
#define poll-delay
@end example

@node Running configur,  , Editing ctdlcnfg.sys, Configuration
@subsection Running configur
@pindex configur
@cindex Configuring
@cindex Running configur

When you've edited @file{ctdlcnfg.doc} to your satisfaction and saved it
as @file{ctdlcnfg.sys}, you're ready to run the configuration program,
@code{configur}.  Ensure that the current directory is the one in which
@file{ctdlcnfg.sys} resides, and then invoke @code{configur} by typing its
name (if you're using a shell), or by clicking on its icon (if you're using
the @sc{gem} desktop).  Don't supply any arguments.

@code{configur} should run and begin to display various messages about what
it's doing.  One of the first things it will do is stop to report that it
can't find certain directories (the ones you specified in @file{ctdlcnfg.sys})
and will ask you whether you'd like @code{configur} to create them.  Answer
`yes'.  It will then proceed to create various system files.
If anything is screwed up with your configuration, or if @code{configur}
encounters
any other error, it will complain and probably stop.  If this happens you
may have to go back and edit @file{ctdlcnfg.sys} some more.  (A good rule
of debugging is ``Never change more than one thing at a time.'')

If @code{configur} is successful, it will leave a file called
@file{ctdltabl.sys} in the same directory as @file{ctdlcnfg.sys}.  This file
contains all of the information that @code{citadel} and the rest of the
Fnordadel programs need to run properly.

@node Bringing Up The System, Backing Up, Configuration, Fifteen Minute Guide
@section Bringing Up The System
@pindex citadel
@cindex Running citadel

If you've made it this far, it means that @code{configur} has run and has
deposited @file{ctdltabl.sys} on your disk.  Now you're ready to bring up
the @sc{bbs} for the first time.  To do this, run @code{citadel}.  You don't
need to pass it any parameters.

When @code{citadel} runs, you'll first see a few lines of identifying
bumph, followed by the contents of @file{banner.blb}, which lives in your
help files directory (specified by
@vindex helpdir
@code{#helpdir} in @file{ctdlcnfg.sys}).
(As with all help files, you can edit this with a normal @sc{ascii} text
editor to reflect details of your own system.)  Next you'll see some more
gibberish, and finally a prompt consisting of a line of helpful reminders
of commands to use, and another line that looks something like this:
@example
Lobby>
@end example

@node Logging in, Giving yourself power, Bringing Up The System, Bringing Up The System
@subsection Logging in
@cindex Logging in

The first thing to do now is to login.  To do this, you must first bring
Fnordadel into ``console mode'' by hitting the @samp{<ESC>} key.  Now type
@code{[L]ogin} (i.e., type @samp{L} and watch the @sc{bbs} echo @samp{login}).
The @sc{bbs} will now do one of two things, depending on whether you told it (via
the @code{getname} parameter in @file{ctdlcnfg.sys}) that you wanted it to
log users in using their usernames and passwords, or with just their
passwords.  If the former, you'll see
@example
login:
@end example
@noindent
Type the username you wish to use on your system; it should match the one you
defined in @file{ctdlcnfg.sys} as
@vindex sysop
@code{#sysop}, and should not be more than
19 characters long.  The @sc{bbs} will then ask:
@example
password:
@end example
@noindent
at which point you should type the password you wish to use; passwords may
be no longer than 19 characters, and should @emph{not} be easily guessable.

If you told the system that you'd like it to use passwords only when logging
people in, then you'll instead see:
@example
Enter password (just carriage return if new):
@end example
@noindent
Since you're new, just hit @samp{<CR>}.

In either case, the @sc{bbs} will now reply:
@example
No record. Enter as new user? (Y/[N]):
@end example
@noindent
Answer @samp{Y} for `yes'.  The system will then ask you a series of questions
about your desired user configuration.   Answer them however you like, but
when the system asks
@example
Are you an experienced Citadel user? (Y/[N])
@end example
@noindent
you'll probably want to answer @samp{No}.  The system may then print out a
warning about choosing an intelligent password.

If you haven't told the system your name yet, it will now ask:
@example
What is your name:
@end example
@noindent
and you should tell it.

If you haven't given it a password yet, it will now ask for one:
@example
What is your password:
@end example
@noindent
and you should give it one, of no more than 19 characters.

The @sc{bbs} will now reply with:
@example
Name: @var{username}
Password: @var{password}

OK? (Y/N):
@end example
@noindent
Type @samp{y} to accept it, or @samp{n} if you want to change something.

You will now be logged in to your @sc{bbs}.  You will see the ``room prompt'' again:
@example
Lobby>
@end example

@node Giving yourself power,  , Logging in, Bringing Up The System
@subsection Giving yourself power
@cindex Sysop privileges
@cindex Aide privileges

If you've done as we suggested and logged in using the name you specified as
@vindex sysop
@code{#sysop} in @file{ctdlcnfg.sys}, you'll find that you have magically been
given Sysop, Aide and Network privileges.  If you didn't, then you'll want to
assign these privileges to yourself manually.  To do this, hit @samp{^L} at
the room prompt.  You should see
@example
sysop cmd:
@end example
@noindent
which is the prompt for the Sysop command menu.  Here, as elsewhere, you can
type a @samp{?}
to see a list of options, but right now we're here on business, so type
@samp{U}.  You'll see
@example
status cmd:
@end example
@noindent
which is the prompt for the ``user status'' menu.  Type @samp{S} for
@code{[S]ysop privileges}, and the system will ask you for the name of a user
on whom to bestow Sysop privileges.  Type the name you logged in with and 
answer the confirmation
@example
@var{username} gets Sysop privileges - confirm? (Y/[N]):
@end example
@noindent
with @samp{Yes}.

You should repeat the above exercise using the @code{[N]etwork privileges}
command to give yourself network privs.

@node Backing Up, Doing It Properly, Bringing Up The System, Fifteen Minute Guide
@section Backing Up
@cindex Backups

There are lots of things you can do now, but we recommend the following:
@itemize @bullet
@item
If you aren't at the room prompt but are still in one of the menus under the
@samp{sysop cmd:} menu, type @samp{X} for @code{e[X]it} until you
reach the room prompt.
@item
Type @samp{T} for @code{[T]erminate} and confirm with @samp{Yes}.  This is to
log you off the system.  The system will return to ``modem mode'' where it
is waiting for a caller.
@item
Press @samp{<ESC>} and @samp{^L} to get to the Sysop menu again.
@item
Type @samp{Q} for @code{[Q]uit Fnordadel}.  This is to exit from @code{citadel}
and return you to your shell or desktop.  Confirm the quit with @samp{Yes}.
@end itemize

Now that you're back on the shell or desktop, you should figure out how to
back your system up and do it for practice.  If you're running from a @sc{ram}disk,
you should copy all files down onto a physical disk.  You should make copies
of the physical floppies on which you run the system, if you use floppies.
If you use a hard disk, make a directory on a separate partition (or better
yet, a separate drive) and copy the contents of your @sc{bbs} directory into it.

We Fnordadelians recommend that you keep at least two sets of backups on
floppy disks, which you alternate between every other backup session.  This
is to guard against data file corruption which might go unnoticed until after
one backup has been made---if you have more than one backup, your chances
of possessing an uncorrupted one are greater.

If you ever need to restore your system from a backup, you should restore
the @emph{entire} backup, unless you are very familiar with the interactions of
various system files and therefore know what you are doing.  Mixing old and new
files can have strange and often bad results, especially with respect to
networking.  Play it safe and restore all matching system files, unless you
have a very good reason not to.

@node Doing It Properly,  , Backing Up, Fifteen Minute Guide
@section Doing It Properly

There, you've got it up and running.  Sort of.  Now we recommend
that you do one or both of the following things:
@enumerate
@item
Sit down with a large cup of something liquid, preferably containing caffeine,
and read through parts of this manual.  You should absolutely read
@ref{Sysop Theory}, and should skim @ref{User Command Reference},
@ref{Aide and Co-Sysop Command Reference}, and
@ref{The Sysop Command Reference}.
Read the remaining chapters as your interest and
persistence dictates.
@item
Bring up @code{citadel} again and start playing around---create some rooms,
enter some messages, and generally goof off.  You'll learn about how the
user interface and the system in general works, and you can't hurt much.
(You @emph{did} make a backup, didn't you?).
@end enumerate

At bare minimum you will want to go through the help files directory and
edit most of the files that end in @samp{.blb}---these are ``blurb'' files
like the banner, the logout notice and so on, which you should customize.
You should also edit two of the @samp{.hlp} files: @file{policy.hlp}
(your system policy), and @file{localbbs.hlp} (a listing of other systems).
(The @samp{.mnu} files should be left alone; these are the command menus,
and there's no good reason to change them unless you don't like the format.)
You will probably also want to go through @file{ctdlcnfg.sys} again and
fine-tune some of the more esoteric options.
