GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/bbs/fn132bin/fdman/chapter.09

Text File | 1991-09-03 | 18KB | 417 lines

Chapter 9:  Doors                                                        126




9  Doors


   The Fnordadel __door__  mechanism allows the  Sysop to provide access  to
external programs  from within  the 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.



9.1  Defining Doors

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


9.1.1  Format of ctdldoor.sys

   The `ctdldoor.sys' file  consists of any number  of lines (each of  which
defines a separate door), in the following format:

      <door> <mode> <program-name> [command tail] [#comment]

   The fields  should be separated  by white-space (i.e.,  spaces or  tabs).
The meanings of the individual fields are as follows:

door       The name that Fnordadel will use to refer to this  door.  It must
           be unique among all the doors you have defined.

mode       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):

           `u'        Anyone may use this door.

           `a'        Only  Aides,  Co-Sysops and  the  Sysop may  use  this
                      door.

           `s'        Only Co-Sysops and the Sysop may use this door.

           `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).

           `c'        Only users on the system console may use this door.

           `m'        Only users on the modem may use this door.

           `d'        This door  must be  executed from  within a  directory
                      room.



Chapter 9:  Doors                                                        127




           `r'        For `d' above; the directory must be readable.

           `w'        For `d' above; the directory must be writable.

           `t'        The user may provide a command tail for this command.

           `n'        Pass the  user name  to this  command as  part of  the
                      command tail (as the end of the tail).

           `x'        This door  is a  ``system'' door.   See Section  9.3.1
                      [System doors], page 130.

           `v'        This door  is an  ``archiver'' door,  defining a  file
                      archiver which  Fnordadel will use  to read the  table
                      of  contents of  archive  files.   See  Section  9.3.2
                      [Archiver doors], page 130.

           `p'        This  door is  a ``protocol''  door,  defining a  file
                      transfer  protocol.     See  Section  9.3.3  [Protocol
                      doors], page 131.

           `h'        This  door  will   be  executed  from  the   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 `l'  mode is  also present,  it will  override
                      this mode.

           `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 `!?' list in that room, and  will only be runnable
                      in  that room.    If the  room  name contains  spaces,
                      replace them with `_' in the door declaration.

                      If  a  mode   string  ended  with  `iFoo_blort',   for
                      example,  this particular  door is  tied  to room  Foo
                      blort.   If Foo blort  is a directory room,  Fnordadel
                      will make  the room's directory the working  directory
                      for the door  when it is run.   The `i' mode  can't be
                      used with the `l' mode, described next.

           `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  `lc:\bin',  for  example,  Fnordadel  will  make
                      `c:\bin' the  current working  directory when  running
                      this command.   The  `l' mode can't  be used with  the
                      `i'  mode, described  above.   If  used  with the  `h'
                      mode, `l' takes precedence.

program-name
           The  full pathname,  including  the  filename extension,  of  the
           program attached to this door.



Chapter 9:  Doors                                                        128




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
           `n') are appended after everything else.

comment    Also optional.  This field must be preceded by a  `#'.  It allows
           you to put  in a short description  of what the door does,  which
           users will see when they hit `!?'.


9.1.2  Example door definitions

   Here are some sample door definitions, some of which you  may want to use
on your system:

      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

   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 `clog.man' for more on clog.)

   The second  example is for  Sysop and  Co-Sysop use only  (note the  mode
string  of `s').    It runs  clog and  passes  it the  argument `-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
`rz.ttp', which is kept in `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  `udwt'; the `w' means  that this door is only  usable in
rooms which allow uploads.  Makes sense, right?



9.1.3  Notes

  o 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 `l' to specify another directory.

  o User-supplied command tails  (enabled with `t' in the mode  string) will
    be  scanned for occurences  of `\'  and `:' 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).



Chapter 9:  Doors                                                        129




  o 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 `l<dirname>'.  This is the most  common problem
    in getting many doors to run.

  o 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 `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.

  o The  syntax of  door definitions  may be  checked by  using the  utility
    program ckdoor.  See `ckdoor.man' for details of its usage.



9.2  The User Interface

   A door command, from the user's point of view, is very simple:

      !door [command-tail]

Simply type a `!', 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  `rz' from
Section 9.1.2 [Example  doors], page 128,  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 `rz' to  download the files `foo',  `bar',
and `blort', the user would simply say:

      !rz foo bar blort

at the room prompt.   The program `c:\bin\rz.ttp' will be run, and  `foo bar
blort' will be passed to it as a command tail.  Easy, huh?

   Typing `!?' 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 `sd', for example, in  the mode string will not
be listed when an Aide does `!?' in a non-directory room.

   Also, overall door  access can be controlled  by the door privilege  flag
in  each  user's account,  and  the  #alldoor  flag  in `ctdlcnfg.sys'.
See  Section 5.2  [User Status  Commands], page  80,  for more  information,
as well  as the  #alldoor description  in `ctdlcnfg.doc',  and the  flipbits
documentation in `flipbits.man'.



Chapter 9:  Doors                                                        130




9.3  Special Kinds of Doors


9.3.1  System doors

   Doors with  a mode  of `x'  are special __system__  doors.   These  doors
currently are  no different than doors  with a mode of  `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:   `login'  (run automatically  when any  user logs  in);
`logout' (run  automatically when  any user  logs out);  and `newuser'  (run
automatically when  a new  user logs  in the  first time).    Here are  some
examples:

      login   x       c:\bin\cookie.tos
      newuser nx      d:\bbsprogs\survey.ttp

   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  `n').  Note that all of these  special doors
must have  the exact name  as given here  (`login', `logout' or  `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.



9.3.2  Archiver doors

   Doors with  a mode of  `v' are __archiver__  doors.   These will  usually
not be called directly  using the `!door' syntax, but indirectly,  using the
.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 .arc file type.  Here's a couple of examples.

   In your `ctdlcnfg.sys' file, put:

      #archiver ZOO zootoc
      #archiver LZH lzhtoc

In your `ctdldoor.sys' file, put:

      zootoc  tdrv    c:\bin\zoo.ttp          v
      lzhtoc  tdrv    c:\bin\lharc102.ttp     v

Both doors take command  tails (`t'), are usable only in  readable directory
rooms  (`dr'), and  are flagged  as  archiver doors  (`v').    To use  them,
all a  user needs to  do is  enter commands like  `.RH foobar.zoo' and  `.RH
blort.lzh'.



Chapter 9:  Doors                                                        131




9.3.3  Protocol doors

   Doors with a mode of `p' are __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
`.RH' command.  For example, suppose you defined a door like:

      rz      tdrp    c:\bin\rz.ttp   Zmodem-download

Then  users could  download  files using  the  Zmodem transfer  protocol  by
entering  a  command  like  `.RZFfoo.bar',   which  would  echo  like  .Read
Zmodem-download File foo.bar.  Look for this in an upcoming release.


9.3.4  The shell door

   If you have a door  which is named `shell', it will override  the setting
of the #shell  variable in `ctdlcnfg.sys'.   See `ctdlcnfg.doc'.   This door
is meant to  be a program like command.tos,  PCOMMAND, or gulam.   Executing
the `!shell' door  is equivalent to executing  the [O]utside command in  the
Sysop menu; see Section 5.1 [Sysop Special Functions], page 75.



9.3.5  Fnordadel as a door

   It  is  theoretically  possible  to  run  Fnordadel  itself  as  a  door!
Unfortunately, this  currently will not  work if your  main 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:

      citadel +door

   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 citadel  if you wish, but  do
not use  `+multi'.   Also, you may  need to avoid  using `+line', since  the
status line may screw up your main system.


9.4  Notes and Caveats



Chapter 9:  Doors                                                        132




9.5  Door Problems

   Getting  doors to  work  can  sometimes  be a  tricky  thing,  even  if
everything looks good and ckdoor doesn't complain  about your `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  a
utility program called 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 *real* door program, which will hopefully be able  to process the new
format of the parameters.

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

Before:    foobar ut c:\blort\foobar.tos -dv

After:     foobar ut c:\fnordbin\doorwrap.tos c:\blort\foobar.tos -dv

   For  more  information on  doorwrap,  see  `doorwrap.man'.     For  other
compatibility and support  information, see Section 13.8  [Compatibilities],
page 168, and Appendix A [Fnordadel Support], page 170.

  o 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 `login', `logout', and `newuser'.

  o 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 BBS and anything else accessible.

  o 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 #maxtime parameter in  `ctdlcnfg.sys' to place some  limits
    on users' abilities  to monopolize your system.  See  `ctdlcnfg.doc' and
    Chapter 10 [Anti-Ruggie Measures], page 133, for details.

  o If you  have problems with  people using doors  and screwing up events
    you have  defined, see the #eventclosetime parameter  in `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.