
     .--------------------------.
     | Mystic BBS Linux Manual  |-------------------------------------------
     `--------------------------'

      Table of Contents:
			
         Section                                          Description
         ------------------------------------------------------------
       - 1.0 ............................. About Mystic BBS for Linux
           | 1.1 ....................................... General Info 
           | 1.2 ................................What Is This Manual? 
       - 2.0 .................................. Installing Mystic BBS
           | 2.1 ............................... Installation Program
           | 2.2 .......................... Creating Linux User/Group
           | 2.3 ......................... Setting Directory Security
           | 2.4 .............................. Logging Into Your BBS
       - 3.0 .......................................... Miscellaneous
           | 3.1 ........................... Displaying ANSI in Linux
           | 3.2 ....................... Installing doors under Linux
           | 3.3 ...........................................Archivers
       - 4.0 .........................................Advanced Topics
           | 4.1 ...................................Security Theories
           | 4.2 .................................Automatic BBS Login
         ------------------------------------------------------------
				 
     .----------------------------------.
     | 1.0   About Mystic BBS For Linux |-----------------------------------
     `----------------------------------'

      1.1 General Information
      -----------------------

      Mystic BBS is one of the first DOS-like BBS packages available under
      the Linux platform.  Anyone familure with the Telegard-like BBS
      packages under DOS should find Mystic refreshing under Linux.

      UPDATE: This document was written many many years ago and could
      contain some outdated information.  For the time being, Mystic
      still must have its telnet sessions started by an inetd-type
      service.  However, POP3, SMTP, FTP, etc are all handled internally
      by MIS (Mystic Internet Server).

      If you are having problems, please find your nearest support outlet
      for help!


      1.2 What Is This Manual
      -----------------------

      This manual has been written to address certain Linux-specific common
      problems that you may have with Mystic BBS and Linux.  Running a BBS
      under Linux is a little bit different than what you might be used to,
      given the vast differences between Unix-like operating systems and
      operating systems like Windows or OS/2.

      We suggest that you read this document completely before attempting to
      setup your BBS.  We also suggest that you reference this manual if you
      are having problems just in case you missed something the first time!

     .--------------------------------------.
     | 2.0   Installing Mystic BBS Software |-------------------------------
     `--------------------------------------'

      2.1 Running The Installation Program
      ------------------------------------

      After the Mystic BBS distribution archive (mysl_XXX.zip) has been
      extracted, you will notice a binary file called "install."  This is
      the Mystic Installation program, which unpacks Mystic into the
      directories that you define.

      To run the install program type "./install" and press the ENTER key.

      Once inside the installation program you can choose to install Mystic
      or read the changes/additions since the last release of Mystic.

      2.2 Creating Linux BBS User
      ---------------------------

      Once the installation program has finished, you will want to create
      a new user for your system.  The new user you add will be the account
      used to access the BBS once someone is connected to your Linux box.

      To add a new user type "adduser bbs" and it should create the user
      "bbs" for you.

      Now that you've created the bbs user account, you'll want to setup
      Mystic as the shell for that account, and disable the password.  To
      do this, you'll need to edit the /etc/passwd file with a text editor.
      Find the listing for the bbs user you just added (should be at the
      bottom).  The entry will look something like this:

         bbs:!%343t1a:1004:200:bbs:/users/bbs:/bin/sh

      The above fits the following format:

        loginname:password:usernumber:usergroup:username:homedir:shell

      The password, homedir, and shell fields need to be changed.  Remove
      the password all together, then change the homedir to the directory
      you installed Mystic into.  Finally, set the shell to run the Mystic
      binary in the Mystic directory.  The result should look something
      like this:

         bbs::1004:200:bbs:/mystic:/mystic/mystic

      2.3 Setting Directory Security
      ------------------------------

      Now that you've added the bbs user, you'll need to set the security
      attributes in the Mystic directory.  You need to make the bbs user
      OWN that directory and all files within it.  To do this, you can
      type: chown -R bbs /mystic

      The security attributes are the main cause of wierd actions from
      within Mystic.  If one of the files Mystic needs to access is owned
      by someone other than the BBS user, Mystic will not be able to access
      it.  You can imagine that this can cause some problems! =]

      Also note that when Mass Uploading any files into the BBS, you will
      probably need to chown them so they belong to the BBS user.  If Mystic
      cannot access the file when a user tries to download it, it will not
      be sent.

      Files that are uploaded via Zmodem should be fine, because they were
      sent to your system by the BBS user.

      As a general problem solving action, its not always a bad idea to
      chown -R bbs /mystic whenever something isn't working or your having
      a problem, just to make sure that everything is owned by the BBS user.

      2.4 Logging Into Your BBS
      -------------------------

      Now that you've got everything installed, you can try to log into your
      BBS.  Exit your account back to your system's login prompt.  Type BBS
      and press ENTER and Mystic should load.  You can now login and use
      your BBS!

      Note that if you ever login or edit Mystic's configuration as any
      user other than your bbs user, that user may have security rights to
      that file.  You may need to chown it as described in the previous
      section for Mystic to work properly.  Because of this, its not
      recommended that you edit or login to your BBS as root or someone
      else.

      The security attributes in Linux are kind of tricky sometimes, but
      once you get more familure with them it is possible to do little
      workarounds to make things easier.  We may expand on this document
      in the future to describe some advanced BBS installations under
      Linux.  For now, this document just gives you the basics with what
      we consider the easiest way to get your BBS up and running.

     .---------------------.
     | 3.0   Miscellaneous |------------------------------------------------
     `---------------------'

      3.1 Displaying ANSI In Linux
      ----------------------------

      Many people will notice that their Linux box will not display ANSI
      and the ANSI character set correctly.  The Mystic installation program
      will automaticly set Linux to use this character set, but after the
      system is rebooted or another program changes this setting, it will
      be back to the way it was.

      The easist way to set Linux to use the USA/ANSI character set is to
      issue this command in the shell: echo -e "\033(U"  You can add that
      to your bootup sequence if you wish, or just manually issue it when
      you want.

      Note that Mystic sets Linux into RAW terminal mode while its running.
      This means that even if ANSI isn't displaying correctly on your local
      system, remote users can still see the ANSI as they should - as long
      as their terminal supports ANSI-BBS.

      The later versions of Mystic will automatically send the US character
      set, but it is still imported to set your terminal to 80x25 and find
      a good font when using Mystic locally.
 
      3.2 Installing Doors Under Linux
      --------------------------------

      At the moment, this guide is not going to cover installing DOS doors
      with DOSEMU under Linux, although it has been done successfully by our
      alpha testers.  What we plan to cover here are notes that might cause
      you some problems otherwise:

          When running an external program within Mystic, you must include
          the full path of the executable.  If you don't, the terminal
          settings will act crazy after returning to Mystic.  For example:

             (BAD) Optional data: sh myscript.sh
             ( OK) Optional data: /bin/sh myscript.sh

          When running an external program using one of the available door
          drop file formats (DOOR.SYS, DORINFO1.DEF, CHAIN.TXT, etc), you
          must keep in mind that these text files are in Unix format text
          files.  If you are running a DOS door under DOSEMU you will more
          than likely have to run a unix2dos text file converter before
          executing the door.

      If you are looking for information on using DOSEMU to run DOS doors
      on your BBS, we've found a good tutorial written by a mystic sysop 
      on the web which might interest you:

      http://clockworkorangebbs.org/dosemu.html

     3.3 Archivers
     -------------

     Currently this document only covers the ZIP archiver for Linux. Other 
     archivers will be added in time.  

     First you need to make sure the archive path is set.  In these 
     examples it is not where the actual program is -- but the location of 
     the script to be executed. This is set under System Configuration -> 
     System Paths.  For this example it is found as below (Item E):

     A. System Path       : /mbbs/
     B. Data Path         : /mbbs/data/
     C. Message Base Path : /home/bbs/msgs/
     D. System Logs Path  : /mbbs/logs/
     E. Archive Path      : /mbbs/scr/
     F. Local QWK Path    : /mbbs/localqwk/
     G. File Attach Path  : /mbbs/attach/
     H. Script (MPE) Path : /mbbs/scripts/

     Below is an example of what the commands should look like in the 
     archive editor.

         A. Name      : Zip
         B. Extension : ZIP
         C. Pack Cmd  : zip.sh %1 %2
         D. Unpack Cmd: unzip.sh %1 %2 %3
         E. View Cmd  : 

     You will notice that the filenames are a little strange.  The ".sh" 
     at the end of the file.  This is because we require to run zip and 
     unzip as a script in order for them to work properly. Below you will
     find the script examples:


     - zip.sh

         #!/bin/bash
         /usr/bin/zip -j9 $1 $2 2>/dev/null >/dev/null

     Line one tells the script that it is using bash as the shell.  This 
     shell is the most commonly used in most if not all Linux distributions.

     Line two runs the zip command. This example assumes that you have zip 
     in /usr/bin, change it according to your setup. The switch -j will 
     "junk" the pathnames. Zip by default will add in the pathname and you 
     don't want that -9 will compress the file as small as possible.

     - unzip.sh

         #!/bin/bash
         /usr/bin/unzip -oCqq $1 $2 -d $3 2>/dev/null >/dev/null

     Line one... same as above...
  
     Line two runs the unzip command.  The switch -o will overwrite 
     existing files without prompting (used in case the temp directory has 
     another archive in it). -C will cause all files to be case 
     insensitive.  This allows you to extract a specific file without 
     problem, in most cases this is the FILE_ID.DIZ. -qq forces unzip to 
     be quiet, meaning display as little info as possible. Which is a 
     little redundant here, but included anyway.

     Finally at the end of each (un)zip command you will find 
     "2>/dev/null >/dev/null", this will send all output by the commands 
     to /dev/null instead of the users screen. You want to keep this in 
     for regular use and remove it when diagnosing a problem.

     .-----------------------.
     | 4.0   Advanced Topics |---------------------------------------------
     `-----------------------'

     4.1 Security Theories
     ---------------------

     WARNING: This section is not a bible on security, its title describes 
              this section pretty nicely. Theory; as in an opinion. Please
              treat this section accordingly.

     It is wise create a specific user AND group for your bbs and all of 
     it's components.  This will stop other users from making changes to 
     the bbs remotely and locally on your machine.  The author of this 
     section makes all changes as the root user just as he would make 
     administrative changes to other components of his system as root.

     When administering your bbs as root any files you create will be 
     created as root you will be required to change the ownership of all 
     bbs related files back to the bbs user and group. To do this, you 
     would execute the following command:

        chown -R bbs.bbs *

     BE CAREFUL WHERE YOU EXECUTE THIS COMMAND!

     Because you will be executing this command a lot, it is our suggestion 
     that you have everything BBS related under the same root directory. 
     This would include all door files, scripts, mailers, tossers etc. By 
     doing this, running the above command will change all file ownerships 
     to bbs.bbs recursively, thus meaning they will all be changed in one 
     command. We would even suggest that you create a script called 
     'ownbbs' that would look like this:

         #! /bin/bash
         cd /mystic             # change this to your bbs directory
         chown -R bbs.bbs *

     Run the above script as root every time you make a change to the bbs 
     as root.  

     4.2 Automatic BBS Login
     -----------------------
     
     Some sysops may want to have their bbs load automatically when a user 
     telnets to port 23 on their system.  With most distributions you 
     would simply telnet to the system and 'login' would take over and 
     prompt the user for the login name (bbs is the suggested name).  With 
     this method the bbs login is seamless, the bbs will automagically 
     appear for the user without any extra steps.  This is a quick and 
     dirty setup, we suggest that you do a little more reading as this may 
     not work on your system.

     Step 1.

     As root, go into /etc and edit inetd.conf, first add this line.

     telnet  stream  tcp     nowait  root    /usr/sbin/tcpd  in.telnetsnoopd

     This will define the parameters for the telnet login which will utilize
     the telnetsnoop feature in linux. Why telnet snoop is required is still
     a mystery to the author... but, it works!

     Next, you need to create a back door into your system if you want to 
     be able to log into your box normally via telnet without accessing the 
     bbs.  To start this process, insert the following line into inetd.conf.

     telnetbd stream tcp     nowait  root    /usr/sbin/tcpd  in.telnetd

     Note the telnetbd at the beginning, this is the name of the service. 
     It doesn't have to be telnetbd, but its good to keep it close to  
     'telnet'.

     The next file we will edit is /etc/services.  This is where you put 
     the above definitions to work.

     The first entry you need should already exist, so no need to change 
     that:

         telnet          23/tcp
         telnet          23/udp

     Next is your back door service, place this near the end of the file 
     and put in the port number that you feel is most comfortable for you.  
     For the example below we are using port 2000.

         telnetbd        2000/tcp
         telnetbd        2000/udp
 
     Next we need to configure ttysnoop to start up the bbs, we do this by 
     editing /etc/snooptab and putting the following line in.  Note the 
     last entry in this line, this points to a script in your main mystic 
     directory.

         *               socket          login   /mbbs/runbbs     
     
     And finally we need to create the 'runbbs' script.  This script will 
     load mystic and run any other commands you want to run when you run 
     the bbs.  A simple example of this script is below:

         #!/bin/sh
         echo -e "\033(U"
         login bbs TERM=linux

     Line one is the tells the script to use sh as the shell. Line two 
     echo's the ansi enabling string as defined earlier in this document 
     and line three automatically logs the bbs user onto the system.

     One final touch would be to create the .hushlogin semiphore file in 
     the bbs users home directory (as defined in /etc/passwd) by running 
     the following command:
 
     touch .hushlogin

     This file will force login to run quietly.  Without it, it usually 
     would display your kernal version and any other important and 
     unsecure information to the user as they logged in.

     This is all there is too it :)

