home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / 311ABETA.ZIP / DOCS.ZIP / sbbscon.txt < prev    next >
Text File  |  2003-10-18  |  10KB  |  254 lines
  1. Synchronet Console Documentation
  2. ================================
  3.  
  4. $Id: sbbscon.txt,v 1.9 2003/10/02 00:34:10 deuce Exp $
  5.  
  6. 1. Introduction
  7. ---------------
  8. The Synchronet Console is the console-mode sysop interface to Synchronet v3.
  9. On Win32 operating systems, this interface (sbbs.exe) is an alternative to 
  10. the graphical Synchronet Control Panel (sbbsctrl.exe). On Unix, this interface
  11. (sbbs) is currently the only option.
  12.  
  13. On Win32 operating systems, the exact same underlying server libraries (DLLs)
  14. are used to service the clients, so from the users perspective there should
  15. be no difference in performance or functionality. The console mode interface
  16. does use fewer system resources than the graphical control panel, so for some
  17. Win32 sysops that wish to conserve system resources, this may be the preferred
  18. interface. But, to date, this interface has been used almost exclusively by
  19. Unix sysops.
  20.  
  21.  
  22. 2. BBS Configuration
  23. --------------------
  24. The system-wide configuration files (ctrl/*.cnf) are edited using the
  25. Synchronet configuration utility (SCFG). The executable filename is 
  26. exec/scfg.exe on Win32 and exec/scfg on Unix.
  27.  
  28. SCFG needs to be told the location of your Synchronet ctrl directory, where
  29. it expects to find the Synchronet configuration (.cnf) files. This can be done
  30. by passing the path to your ctrl directory on the SCFG command line. Example:
  31.  
  32.     scfg /sbbs/ctrl
  33. or:
  34.     scfg /usr/local/sbbs/ctrl
  35.  
  36. or by setting the SBBSCTRL environment variable before running SCFG.  Example:
  37.  
  38. Unix (bash):    export SBBSCTRL=/sbbs/ctrl
  39. Unix (sh):    SBBSCTRL=/sbbs/ctrl && export SBBSCTRL
  40. Unix (csh):    setenv SBBSCTRL /sbbs/ctrl
  41. Win32:        set SBBSCTRL=/sbbs/ctrl
  42.  
  43. Generally speaking, if you are running Linux, your shell is bash.  You can
  44. verify your shell by typing ``echo $SHELL'' at a command line.
  45.  
  46. Many of the Synchronet utilities require this environment variable, so it is
  47. suggested you initialize this environment variable in your system startup 
  48. and/or login scripts. See section 3 for details.
  49.  
  50. The SCFG application supports multiple forms of user interface. The default
  51. interface is currently curses/conio (fullscreen colored text). To use a
  52. different interface, use the -G (graphical) or -D (stdio) command-line
  53. options. There are other command-line options to control the character set
  54. used, escape key delay, monochrome/color mode, etc. Type "scfg -?" to list
  55. all the available command-line options.
  56.  
  57. There are other system-configuration files that are simple text files to be
  58. edited using any ASCII text editor: ctrl/*.cfg and text/*.can. Each of
  59. these files should contain a description of its purpose and usage.
  60.  
  61.  
  62. 3. Initializing the SBBSCTRL Environment Variable
  63. -------------------------------------------------
  64. For Windows NT-based operating systems, goto the Windows Control Panel->
  65. System->Advanced->Environment Variables->System Variables->New...
  66.     Variable:           SBBSCTRL
  67.     Variable Value:     c:\sbbs\ctrl
  68.     (replace c:\sbbs\ctrl with the full path to your ctrl directory)
  69.  
  70. For Windows 9x-based operating systems, edit your C:\AUTOEXEC.BAT file
  71. and add the line:
  72.     SET SBBSCTRL=c:\sbbs\ctrl
  73.     (replace c:\sbbs\ctrl with the full path to your ctrl directory)
  74.  
  75. For Unix bash/sh:
  76. In the home directory of the user the BBS will be running as, edit the file
  77. named either .profile or .bash_profile depending on if you're running bash or
  78. sh and add the line:
  79.  
  80.     SBBSCTRL=/sbbs/ctrl && export SBBSCTRL
  81.     (replace /sbbs/ctrl with the full path to your ctrl directory)
  82.  
  83. For Unix csh/tcsh:
  84. Again, in the home directory of the user the BBS will be running as, in the file
  85. named .tcshrc (for tcsh) or .cshrc (for csh) add the line:
  86.  
  87.     setenv SBBSCTRL /sbbs/ctrl
  88.     (replace /sbbs/ctrl with the full path to your ctrl directory)
  89.  
  90.  
  91. 4. Server Configuration
  92. -----------------------
  93. The server/host-specific configuration options are set with sbbs command-line
  94. options (run "sbbs help" for a list) or by editing the Synchronet
  95. Initialization file (e.g. ctrl/sbbs.ini).
  96.  
  97.  
  98. 4.1 Initialization File
  99. -----------------------
  100. The Synchronet initialization file is a plain text file in Windows ini format.
  101. Lines beginning with a semicolon (;) character are considered comments and
  102. are ignored. Configuration values are grouped into sections. Sections are
  103. defined by a "[section_name]" line. The configuration sections are:
  104.  
  105.     [Global]        - Settings applied to all servers and services
  106.     [BBS]           - Settings applied to the Telnet/RLogin server
  107.     [Mail]          - Settings applied to the SMTP/POP3 mail server
  108.     [FTP]           - Settings applied to the FTP server
  109.     [Web]           - Settings applied to the Web server
  110.     [Services]      - Settings applied to Synchronet services
  111.     [UNIX]          - Settings applied to operations under Unix only
  112.     [SBBSCTRL:*]    - Settings exported from the Synchronet Control Panel
  113.  
  114. Within each section is a list of values (one per line) in the form:
  115.     name=value
  116.  
  117. It is recommended that sysops new to Synchronet, leave the default values
  118. intact unless instructed to do otherwise.
  119.  
  120. The default initalization file is ctrl/sbbs.ini. A different initialization 
  121. filename may be used by specifying the path and filename on the sbbs
  122. command-line. Example:
  123.  
  124.     sbbs /sbbs/ctrl/mybbs.ini
  125.  
  126. If the path and filename of the initialization file is not passed on the
  127. command-line, sbbs will use the SBBSCTRL environment variable to determine
  128. the location of your Synchronet ctrl directory, where it expects to find
  129. either <HOSTNAME>.ini or sbbs.ini.
  130.  
  131.  
  132. 5. For Unix Sysops
  133. --------------------
  134. You will particularily want to pay attention to the [UNIX] section of your
  135. Initialization file.
  136.  
  137. If you do not want to run Synchronet (and all external programs/doors) as
  138. root, you will have to set the User and Group values.
  139.  
  140. If you want Synchronet to fork and run in the background as a daemon, logging
  141. via syslog rather than the local console, set Daemonize=True in this section.
  142.  
  143. To configure syslog and the LogFacility, a good default to use is LogFacility=3
  144. Then, in /etc/syslog.conf you will need to add the line:
  145. local3.*                /var/log/synchronet.log
  146.  
  147. You will have to create this file manually initially by running:
  148. touch /var/log/synchronet.log
  149.  
  150. The send a HUP to syslogd like so:
  151. killall -HUP syslogd
  152.  
  153. You will want to investigate how your system rotates logs and set it up to
  154. rotate synchronet.log also.
  155.  
  156. Further use of the LogFacility setting is beyond the scope of this document.
  157. Read your syslog.conf manpage for more information about this.  In particular,
  158. do NOT use the 'S' setting unless you are familiar with advanced syslogd
  159. configuration.  The S setting will use different facilities for each feature
  160. of Synchronet as appropriate.  Specifically, S will use:
  161.  
  162.     LOG_AUTH
  163.     LOG_DAEMON
  164.     LOG_FTP (If available)
  165.     LOG_MAIL
  166.     LOG_CRON
  167.  
  168.  
  169. 5.1 Terminal Capabilities
  170. -------------------------
  171. As you may have noticed by now, most telnet clients designed for use with
  172. ANSI BBSes do not display fullscreen Unix programs correctly. Included with
  173. Synchronet is a pair of terminal capability definition files that enable you
  174. to run native fullscreen Unix programs and have the output displayed correctly
  175. in a standard ANSI-BBS terminal.  These files are termcap and terminfo,
  176. located in your Synchronet install directory.  Your system will use one or the
  177. other, and it won't hurt to install both.  You will need to be logged in as
  178. root to install the files.
  179.  
  180. Installing the terminfo file:
  181. -----------------------------
  182. 1) Change to the Synchronet install directory (e.g. sbbs/install)
  183. 2) Enter the command ``tic terminfo''
  184.  
  185. Installing the termcap file:
  186. ----------------------------
  187. 1) Change to the Synchroent install dircetory (e.g. sbbs/install)
  188. 2) Enter the command ``cat termcap >> /etc/termcap''
  189. 3) *** FreeBSD Only *** run the command:
  190.     ``cap_mkdb -f /usr/share/misc/termcap.db /etc/termcap''
  191.  
  192. Once the terminal capability files are installed, edit the ExternalTermANSI
  193. value in the [BBS] section of your .ini file to read:
  194.     ExternalTermANSI=ansi-bbs
  195.  
  196.  
  197. 6. Running Synchronet
  198. ---------------------
  199. If you've initialized the SBBSCTRL environment variable and edited your BBS
  200. and server configuration, you are now ready to run Synchronet. You can do
  201. this by simply running exec/sbbs (off of the installation directory).
  202.  
  203.  
  204. 6.1 Running Synchronet Automatically During Boot-up (Unix)
  205. ----------------------------------------------------------
  206. If you want Synchronet to start automatically whenever your system boots,
  207. you will need to set that up using the system rc scripts.  A few example are:
  208.  
  209. FreeBSD:
  210. --------
  211. 1) Set up your BBS to run as a daemon, make SURE it works.
  212.  
  213. 2) Create the following file as /usr/local/etc/rc.d/synchronet.sh owned by
  214.    root, and chmod 555:
  215.  
  216. --- CUT --- /usr/local/etc/rc.d/synchronet.sh --- CUT ---
  217. #!/bin/sh
  218.  
  219. # Replace the path in the following line with your sbbs install DIR
  220. SBBSDIR=/sbbs
  221.  
  222. case "$1" in
  223. start)
  224.         echo -n 'sbbs '
  225.         cd $SBBSDIR/exec
  226.         export SBBSCTRL=$SBBSDIR/ctrl
  227.         export SHELL=/bin/sh
  228.         ./sbbs
  229.         ;;
  230. stop)
  231.         echo "Shutting down Synchronet... "
  232.         kill `cat /var/run/sbbs.pid`
  233.         while ps -p `cat /var/run/sbbs.pid` > /dev/null
  234.         do      sleep 1
  235.         done
  236.         ;;
  237. *)
  238.         echo "Usage: `basename $0` {start|stop}" >&2
  239.         ;;
  240. esac
  241.  
  242. exit 0
  243. --- CUT --- END OF FILE --- CUT ---
  244.  
  245. A note on SysOp paging:
  246. For most systems, the BBS must run as root to page the SysOp.  FreeBSD supports
  247. an alternative method which requires a custom kernel with the option:
  248.  
  249. pseudo-device speaker
  250.  
  251. /dev/speaker should be read/writeable by the user the BBS runs as.
  252.  
  253. /* End of sbbscon.txt */
  254.