@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: doors.tex,v 2.4 91/09/02 01:37:43 adrian Exp $

@node Doors, Anti-Ruggie Measures, Networking, Top
@chapter Doors
@cindex Doors

The Fnordadel
@cindex Doors
@dfn{door} mechanism allows the Sysop to provide
access to external programs from within the @sc{bbs}, in a controllable fashion.
This allows things like online games, additional file transfer protocols, or
whatever you feel like.  This chapter describes the door mechanism.

@node Defining Doors, Door User Interface, Doors, Doors
@section Defining Doors
@cindex Doors, configuration

Doors are defined in the file @file{ctdldoor.sys}, which lives in
your @code{#sysdir}.  It is a simple @sc{ascii} text file, editable
@vindex sysdir
with any text
editor or word processor that will save in @sc{ascii}.  It is read into memory
@pindex citadel
by @code{citadel} when it runs; if you change the file somehow while
Fnordadel is running, you'll have to @code{[Q]uit} from the @sc{bbs} and re-run
@code{citadel} to make the change take effect.

@node Format of ctdldoor.sys, Example doors, Defining Doors, Defining Doors
@subsection Format of ctdldoor.sys
@cindex ctdldoor.sys (file)

The @file{ctdldoor.sys} file consists of any number of lines
(each of which defines a separate door), in the following format:
@cindex Door declaration
@example
<@var{door}> <@var{mode}> <@var{program-name}> [@var{command tail}] [#@var{comment}]
@end example
The fields should be separated by white-space (i.e., spaces or tabs).
The meanings of the individual fields are as follows:
@table @var
@item door
The name that Fnordadel will use to refer to this door.
It must be unique among all the doors you have defined.
@item mode
@cindex Door modes
The set of permissions/restrictions on this door.
It consists of a string of any of these characters (although
some combinations don't make sense):
@table @samp
@item u
Anyone may use this door.
@item a
Only Aides, Co-Sysops and the Sysop may use this door.
@item s
Only Co-Sysops and the Sysop may use this door.
@item z
Only the Sysop may use this door (that's you usually,
but it could also be any Sysop logged in
at the system console, or who has supplied the system
password to get into the Sysop menu).
@item c
Only users on the system console may use this door.
@item m
Only users on the modem may use this door.
@item d
This door must be executed from within a
directory room.
@item r
For @samp{d} above; the directory must be readable.
@item w
For @samp{d} above; the directory must be writable.
@item t
The user may provide a command tail for this
command.
@item n
Pass the user name to this command as part of
the command tail (as the end of the tail).
@item x
This door is a ``system'' door.  @xref{System doors}.
@item v
This door is an ``archiver'' door, defining a file archiver which Fnordadel
will use to read the table of contents of archive files.  @xref{Archiver doors}.
@item p
This door is a ``protocol'' door, defining a file transfer protocol.
@xref{Protocol doors}.
@item h
This door will be executed from the @sc{bbs} home directory (i.e. where
ctdlcnfg.sys lives).  Normally, a door executed in a directory room will
be run from that room's directory.  Some doors don't like that, so this
mode can be set to correct things.  If the @samp{l} mode is also present,
it will override this mode.
@item i
If present, this must be the last mode.  The rest of the mode string is
the name of a room to which the door will be linked.  The door will only
show up in the @samp{!?} list in that room, and will only be runnable in
that room.  If the room name contains spaces, replace them with @samp{_}
in the door declaration.

If a mode string ended with @samp{iFoo_blort}, for example,
this particular door is tied to room @code{Foo blort}.  If @code{Foo blort}
is a directory room, Fnordadel will make the room's directory the working
directory for the door when it is run.  The @samp{i} mode can't be used
with the @samp{l} mode, described next.
@item l
If present, this must be the last mode.  The rest of the mode string is
the directory to which this command will be linked.  If a mode string
ends with @samp{lc:\bin}, for example, Fnordadel will make @file{c:\bin}
the current working directory when running this command.  The @samp{l}
mode can't be used with the @samp{i} mode, described above.  If used with
the @samp{h} mode, @samp{l} takes precedence.
@end table
@item program-name
The full pathname, including the filename
extension, of the program attached to this door.
@item command tail
The optional command tail to pass to this 
door upon execution.  If the door allows a user-supplied 
command tail, it will be appended to this command tail,
and user names (mode character @samp{n}) are appended after
everything else.
@item comment
Also optional.  This field must be preceded by a @samp{#}.  It allows
you to put in a short description of what the door does, which users will
see when they hit @samp{!?}.
@end table

@node Example doors, Door definition notes, Format of ctdldoor.sys, Defining Doors
@subsection Example door definitions

Here are some sample door definitions, some of which you
may want to use on your system:
@example
clog    u       e:\citutil\clog.tos     -t      # 3-column log reader
uclog   s       e:\citutil\clog.tos     -p      # log reader for Sysop
rz      udrt    c:\bin\rz.ttp                   # zmodem download
ez      udwt    c:\bin\sz.ttp                   # zmodem upload
@end example
@pindex clog
The first example provides a quick way for users to get an
up-to-the-minute quickie listing of the user log; it will print
out the names only, in three-column format.  (See @file{clog.man} for
more on @code{clog}.)

The second example is for Sysop and Co-Sysop use only (note the mode string
of @samp{s}).  It runs @code{clog} and passes it the argument @samp{-p} (which
enables the printing of passwords).  You'd use this if someone
forgot their password and you wanted to find out what it was (be
careful of hackers, though).

The third example implements Zmodem downloads via the external
program @file{rz.ttp}, which is kept in @file{c:\bin}.  It passes no command
tail of its own, but it does allow the user to pass a tail in,
so he can specify which file(s) he wants to download.

The fourth example implements Zmodem uploads.  Notice that the
mode string consists of @samp{udwt}; the @samp{w} means that this door
is only usable in rooms which allow uploads.  Makes sense, right?

@node Door definition notes,  , Example doors, Defining Doors
@subsection Notes

@itemize @bullet
@item
In any directory room, the ``current directory'' (for the
purposes of the door program) is always set to be the
directory attached to the room, unless you use the link mode
@samp{l} to specify another directory.

@item
User-supplied command tails (enabled with @samp{t} in the
mode string) will be scanned for occurences of @samp{\}
and @samp{:} characters, and these will be removed.  This
is to stop an unscrupulous user from passing full
pathnames to, say, a file transfer program and gaining
access to private information; users will only be
able to access information to which they have normal
Citadel access (by being in a directory room).

@item
If you're running an online game or something which
requires that it be pointed at a specific directory
(so it can access data files or whatever), use the
mode @samp{l<@var{dirname}>}.  This is the most
common problem in getting many doors to run.

@item
If you want to restrict a door to be used only by certain
users, make a private or invitation-only room, and link the
door to that room using the @samp{i} mode.  If the door program
in question also needs to be linked to a directory in order to
run properly, make the room a directory room pointing at the
needed directory.

@item
The syntax of door definitions may be checked by using
the utility program @code{ckdoor}.  See @file{ckdoor.man} for
@pindex ckdoor
details of its usage.
@end itemize

@node Door User Interface, Special Doors, Defining Doors, Doors
@section The User Interface
@cindex Doors, using

A door command, from the user's point of view, is very simple:
@example
!@var{door} [@var{command-tail}]
@end example
@noindent
Simply type a @samp{!}, followed by the name of the door; if the door
allows or requires a command tail to be passed in, as in the example door
@samp{rz} from
@ref{Example doors}, then it should be separated from the door name by a
space, and the remainder of the door command is taken to be the command
tail.  So, using @samp{rz} to download the files @file{foo}, @file{bar},
and @file{blort},
the user would simply say:
@example
!rz foo bar blort
@end example
@noindent
at the room prompt.  The program @file{c:\bin\rz.ttp} will be run,
and @samp{foo bar blort} will be passed to it as a command tail.  Easy, huh?

Typing @samp{!?} will print out a list of doors accessible from the
current room by the current user.  So you'll notice that the list may
vary, depending on the type of user logged in (Sysop, Co-Sysop, Aide or normal user),
and on the room or type of room the user is in (directory or normal).  Doors
that specify @samp{sd}, for example, in the mode string will not be listed when
an Aide does @samp{!?} in a non-directory room.

Also, overall door access can be controlled by the door privilege flag
in each user's account, and the @code{#alldoor} flag in @file{ctdlcnfg.sys}.
@vindex alldoor
@xref{User Status Commands},
for more information, as well as the @code{#alldoor} description in
@file{ctdlcnfg.doc}, and the @code{flipbits} documentation in
@pindex flipbits
@file{flipbits.man}.

@node Special Doors, Door Notes and Caveats, Door User Interface, Doors
@section Special Kinds of Doors

@node System doors, Archiver doors, Special Doors, Special Doors
@subsection System doors
@cindex Doors, system
@cindex System doors

Doors with a mode of @samp{x} are special
@cindex System doors
@dfn{system} doors.  These doors
currently are no different than doors with a mode of @samp{z} (for use
by the Sysop only), but that may change in the future.  For now,
these doors are intended to be ones that aren't run explicitly by
any user, even the Sysop.  There are three special doors that you
will probably want to define as system doors:
@cindex Login door
@samp{login} (run
automatically when any user logs in);
@cindex Logout door
@samp{logout} (run automatically
when any user logs out); and
@cindex Newuser door
@samp{newuser} (run automatically when a
new user logs in the first time).  Here are some examples:
@example
login   x       c:\bin\cookie.tos
newuser nx      d:\bbsprogs\survey.ttp
@end example
The first example runs a cookie program (something that spits out
a random witty quote) for every user that logs in.  The second
example runs a hypothetical survey program for each new caller,
passing the user's name to the program (mode character @samp{n}).
Note that all of these special doors must have the exact name as
given here (@samp{login}, @samp{logout} or @samp{newuser}).  This
implies that you
can only have one door of each type.  If you need more, you'll need
to write yourself a custom program that calls, in turn, each of the
other programs that you wish to be executed.

@node Archiver doors, Protocol doors, System doors, Special Doors
@subsection Archiver doors
@cindex Archiver doors
@cindex Doors, archiver

Doors with a mode of @samp{v} are
@cindex Archiver doors
@dfn{archiver} doors.  These will usually
not be called directly using the @samp{!@var{door}} syntax, but indirectly,
using the @code{.R(ead) (archive-)H(eader)} command.  These doors enable
users to view the contents of any archive file, even though the
Fnordadel internal code only supports the @code{.arc} file type.  Here's
a couple of examples.

In your @file{ctdlcnfg.sys} file, put:
@vindex archiver
@example
#archiver ZOO zootoc
@vindex archiver
#archiver LZH lzhtoc
@end example
@noindent
In your @file{ctdldoor.sys} file, put:
@example
zootoc  tdrv    c:\bin\zoo.ttp          v
lzhtoc  tdrv    c:\bin\lharc102.ttp     v
@end example
@noindent
Both doors take command tails (@samp{t}), are usable only in readable
directory rooms (@samp{dr}), and are flagged as archiver doors (@samp{v}).
To use them, all a user needs to do is enter commands like
@samp{.RH foobar.zoo} and @samp{.RH blort.lzh}.

@node Protocol doors, The shell door, Archiver doors, Special Doors
@subsection Protocol doors
@cindex Doors, protocol
@cindex File transfer protocol doors
@cindex Protocol doors

Doors with a mode of @samp{p} are
@cindex Protocol doors
@dfn{protocol} doors.  They are currently
not used in any special way by the system, but a coming enhancement
will allow them to function for file transfers sort of like archiver
doors do for the @samp{.RH} command.  For example, suppose you defined a
door like:
@example
rz      tdrp    c:\bin\rz.ttp   Zmodem-download
@end example
@noindent
Then users could download files using the Zmodem transfer protocol by
entering a command like @samp{.RZFfoo.bar}, which would echo like
@code{.Read Zmodem-download File foo.bar}.  Look
for this in an upcoming release.

@node The shell door, Fnordadel as a door, Protocol doors, Special Doors
@subsection The shell door
@cindex Shell, as a door

If you have a door which is named @samp{shell}, it will override the
@vindex shell
setting of the @code{#shell} variable in @file{ctdlcnfg.sys}.  See
@file{ctdlcnfg.doc}.
This door is meant to be a program like @code{command.tos}, @code{PCOMMAND}, or
@code{gulam}.  Executing the @samp{!shell} door is equivalent to executing the
@code{[O]utside} command in the Sysop menu; see @ref{Sysop Special Functions}.

@node Fnordadel as a door,  , The shell door, Special Doors
@subsection Fnordadel as a door
@cindex Door, running Fnordadel as
@cindex Running Fnordadel as a door

It is theoretically possible to run Fnordadel itself as a door!
Unfortunately, this currently will not work if your main @sc{bbs}
software is also STadel or Fnordadel (we're working on it), although it
should work from within fOrEm and others that support doors.  To
run Fnordadel as a door from another system, set it up as you
would if you were running it stand-alone.  Then create a door on
your main system to change directory into your Fnordadel's home
directory, and invoke it with the command:
@example
citadel +door
@end example
@pindex citadel
@pindex +door (citadel)
When Fnordadel comes up, it will assume that a user is already
connected.  Thus, no modem commands or controls will be used.
When the user terminates, Fnordadel will exit and return control
to the calling program.  You may supply other parameters to
@pindex +line (citadel)
@pindex +multi (citadel)
@code{citadel} if you wish, but do not use @samp{+multi}.  Also, you may
need to avoid using @samp{+line}, since the status line may screw up
your main system.

@node Door Notes and Caveats
@section Notes and Caveats

@node Door Problems
@section Door Problems
@cindex Door problems
@cindex Problems with doors

Getting doors to work can sometimes be a tricky thing, even if
@pindex ckdoor
everything looks good and @code{ckdoor} doesn't complain about your
@file{ctdldoor.sys} file.  A common problem with programs used as
doors is that they don't process command line parameters the same
way Fnordadel does.  Fnordadel passes parameters to all doors using
the Atari-sanctioned ``ARGV'' method, which is used by Mark Williams C,
Gnu C, and possibly other languages also.  However, many languages do
not use this method of handling command line parameters, and so won't
work as Fnordadel doors.

To get around this problem is not difficult, hopefully.  We provide
@pindex doorwrap
a utility program called @code{doorwrap}, whose only purpose is to
take a parameter list from Fnordadel, convert it to a different form,
and pass the result on to the @emph{real} door program, which will
hopefully be able to process the new format of the parameters.

To use @code{doorwrap}, declare your door exactly as you normally would,
but insert the full pathname of @code{doorwrap} immediately prior to
the pathname of the real door program.  Here's an example:

@table @asis{}
@item Before:
foobar	ut	c:\blort\foobar.tos -dv

@item After:
foobar	ut	c:\fnordbin\doorwrap.tos c:\blort\foobar.tos -dv
@end table

For more information on @code{doorwrap}, see @file{doorwrap.man}.
For other compatibility and support information, @pxref{Compatibilities},
and @ref{Fnordadel Support}.

@itemize @bullet
@item
If someone drops carrier while running a door, the door program
(depending on whether it's been written to detect the loss of
carrier) will probably be sitting waiting for the user to type
something when the next call comes in; the next caller may well
end up dumped right into the door where the last caller left
off.  Depending on the program, it may well be a Bad Thing.
Be really careful of this problem when defining special doors like
@samp{login}, @samp{logout}, and @samp{newuser}.

@item
Be careful when giving out access to things like shell programs
and stuff; anything that gives the user access to your whole
file system (and especially stuff like shells that gives them
access to things like directory removal commands) is potentially
hazardous to the health of your @sc{bbs} and anything else accessible.

@item
If you have people hogging a lot of system time using doors, there
isn't much you can do about it other than turf the doors.  However,
you can set the @code{#maxtime} parameter in @file{ctdlcnfg.sys} to place some
@vindex maxtime
limits on users' abilities to monopolize your system.  See
@file{ctdlcnfg.doc} and @ref{Anti-Ruggie Measures}, for details.

@item
If you have problems with people using doors and screwing up events
@vindex eventclosetime
you have defined, see the @code{#eventclosetime} parameter in
@file{ctdlcnfg.doc}.
It lets you specify a cut-off time in minutes.  If an event is that
number of minutes (or less) away from happening, users won't be
allowed to start any doors.
@end itemize