Synchronet Console Documentation ================================ $Id: sbbscon.txt,v 1.31 2006/05/16 19:14:17 deuce Exp $ 1. Introduction --------------- The Synchronet Console is the console-mode sysop interface to Synchronet v3. On Win32 operating systems, this interface (sbbs.exe) is an alternative to the graphical Synchronet Control Panel (sbbsctrl.exe). On Unix, this interface (sbbs) is currently the only option. On Win32 operating systems, the exact same underlying server libraries (DLLs) are used to service the clients, so from the users perspective there should be no difference in performance or functionality. The console mode interface does use fewer system resources than the graphical control panel, so for some Win32 sysops that wish to conserve system resources, this may be the preferred interface. But, to date, this interface has been used almost exclusively by Unix sysops. 2. BBS Configuration -------------------- The system-wide configuration files (ctrl/*.cnf) are edited using the Synchronet configuration utility (SCFG). The executable filename is exec/scfg.exe on Win32 and exec/scfg on Unix. SCFG needs to be told the location of your Synchronet ctrl directory, where it expects to find the Synchronet configuration (.cnf) files. This can be done by passing the path to your ctrl directory on the SCFG command line. Example: scfg /sbbs/ctrl or: scfg /usr/local/sbbs/ctrl or by setting the SBBSCTRL environment variable before running SCFG. Example: Unix (bash): export SBBSCTRL=/sbbs/ctrl Unix (sh): SBBSCTRL=/sbbs/ctrl && export SBBSCTRL Unix (csh): setenv SBBSCTRL /sbbs/ctrl Win32: set SBBSCTRL=/sbbs/ctrl Generally speaking, if you are running Linux, your shell is bash. You can verify your shell by typing ``echo $SHELL'' at a command line. Many of the Synchronet utilities require this environment variable, so it is suggested you initialize this environment variable in your system startup and/or login scripts. See section 3 for details. The SCFG application supports multiple forms of user interface. The default interface is currently X11 if available or curses/conio (fullscreen colored text) if not. To use a different interface, use the -iD (stdio), or -iA (ANSI output) command-line options. There are other command-line options to control the character set used, escape key delay, monochrome/color mode, etc. Type "scfg --help" to list all the available command-line options. There are other system-configuration files that are simple text files to be edited using any ASCII text editor: ctrl/*.cfg and text/*.can. Each of these files should contain a description of its purpose and usage. 3. Initializing the SBBSCTRL Environment Variable ------------------------------------------------- For Windows NT-based operating systems, goto the Windows Control Panel-> System->Advanced->Environment Variables->System Variables->New... Variable: SBBSCTRL Variable Value: c:\sbbs\ctrl (replace c:\sbbs\ctrl with the full path to your ctrl directory) For Windows 9x-based operating systems, edit your C:\AUTOEXEC.BAT file and add the line: SET SBBSCTRL=c:\sbbs\ctrl (replace c:\sbbs\ctrl with the full path to your ctrl directory) For Unix bash/sh: In the home directory of the user the BBS will be running as, edit the file named either .profile or .bash_profile depending on if you're running bash or sh and add the line: SBBSCTRL=/sbbs/ctrl && export SBBSCTRL (replace /sbbs/ctrl with the full path to your ctrl directory) For Unix csh/tcsh: Again, in the home directory of the user the BBS will be running as, in the file named .tcshrc (for tcsh) or .cshrc (for csh) add the line: setenv SBBSCTRL /sbbs/ctrl (replace /sbbs/ctrl with the full path to your ctrl directory) 4. Server Configuration ----------------------- The server/host-specific configuration options are set with sbbs command-line options (run "sbbs help" for a list) or by editing the Synchronet Initialization file (e.g. ctrl/sbbs.ini). 4.1 Initialization File ----------------------- The Synchronet initialization file is a plain text file in Windows ini format. Lines beginning with a semicolon (;) character are considered comments and are ignored. Configuration values are grouped into sections. Sections are defined by a "[section_name]" line. The configuration sections are: [Global] - Settings applied to all servers and services [BBS] - Settings applied to the Telnet/RLogin server [Mail] - Settings applied to the SMTP/POP3 mail server [FTP] - Settings applied to the FTP server [Web] - Settings applied to the Web server [Services] - Settings applied to Synchronet services [UNIX] - Settings applied to operations under Unix only Within each section is a list of values (one per line) in the form: name=value It is recommended that sysops new to Synchronet, leave the default values intact unless instructed to do otherwise. The default initalization file is ctrl/sbbs.ini. A different initialization filename may be used by specifying the path and filename on the sbbs command-line. Example: sbbs /sbbs/ctrl/mybbs.ini If the path and filename of the initialization file is not passed on the command-line, sbbs will use the SBBSCTRL environment variable to determine the location of your Synchronet ctrl directory, where it expects to find either .ini or sbbs.ini. If you are using the Synchronet Control Panel (for Win32) and want to use your current settings for the Synchronet Console or NT Services, you can export your settings to your ctrl/sbbs.ini file using the File->Export Settings menu option. 5. For Unix Sysops -------------------- You will particularily want to pay attention to the [UNIX] section of your Initialization file. If you do not want to run Synchronet (and all external programs/doors) as root, you will have to set the User and Group values. Also, the file permissions/ownership should be such that the other user would have read and write access to them. The best way to accomplish this is a command like: chown -R sbbsuser:sbbsgroup /sbbs If you want Synchronet to fork and run in the background as a daemon, logging via syslog rather than the local console, set Daemonize=True in this section. To configure syslog and the LogFacility, a good default to use is LogFacility=3 Then, in /etc/syslog.conf you will need to add the line: local3.* /var/log/synchronet.log Depending on how your vendor set up syslog.conf initially, you may also want to exclude local3.* from other log files (Noteably /var/log/messages) how to do this varies with your syslogd implementation, but for BSD based ones (Which BSD and many Linux distros use) you would add ";local3.none" to the end of the first field in the /var/log/messages line. You will have to create this file manually initially by running: touch /var/log/synchronet.log Then send a HUP to syslogd like so: killall -HUP syslogd You will want to investigate how your system rotates logs and set it up to rotate synchronet.log also. Further use of the LogFacility setting is beyond the scope of this document. Read your syslog.conf manpage for more information about this. In particular, do NOT use the 'S' setting unless you are familiar with advanced syslogd configuration. The S setting will use different facilities for each feature of Synchronet as appropriate. Specifically, S will use: LOG_AUTH LOG_DAEMON LOG_FTP (If available) LOG_MAIL LOG_CRON 5.1 Terminal Capabilities ------------------------- As you may have noticed by now, most telnet clients designed for use with ANSI BBSes do not display fullscreen Unix programs correctly. Included with Synchronet is a pair of terminal capability definition files that enable you to run native fullscreen Unix programs and have the output displayed correctly in a standard ANSI-BBS terminal. These files are termcap and terminfo, located in your Synchronet install directory. Your system will use one or the other, and it won't hurt to install both. You will need to be logged in as root to install the files. Installing the terminfo file: ----------------------------- 1) Get the Synchronet ANSI-BBS terminfo file from: http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/install/terminfo 2) Enter the command ``tic terminfo'' Installing the termcap file: ---------------------------- 1) Get the Synchronet ANSI-BBS termcap file from: http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/install/termcap 2) Enter the command ``cat termcap >> /etc/termcap'' 3) *** FreeBSD Only *** run the command: ``cap_mkdb -f /usr/share/misc/termcap /etc/termcap'' Once the terminal capability files are installed, edit the ExternalTermANSI value in the [BBS] section of your .ini file to read: ExternalTermANSI=ansi-bbs Note: Once again, many Linux distros do not have a termcap. This is fine. You do NOT need to install the termcap-compat package. If termcap isn't installed, it means nothing uses it. Only if there is a termcap do you need to add the ansi-bbs termcap definition. 6. Running Synchronet --------------------- If you've initialized the SBBSCTRL environment variable and edited your BBS and server configuration, you are now ready to run Synchronet. You can do this by simply running exec/sbbs (off of the installation directory). 6.1 Running Synchronet Automatically During Boot-up (Unix) ---------------------------------------------------------- If you want Synchronet to start automatically whenever your system boots, you will need to set that up using the system rc scripts. A few example are: Linux: ------ 1) Get the Synchronet service run script (init file) from: http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/install/init.d/sbbs 2) Copy the run script (sbbs) into your /etc/init.d directory (if you don't have this directory, then your Linux distribution isn't supported by this file). 3) Add the Synchronet system service: # chkconfig --add sbbs 4) Start the Synchronet system service: # /etc/init.d/sbbs start FreeBSD: -------- 1) Get the Synchronet service run script (init file) from: http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/install/rc.d/sbbs 2) Copy the run script (sbbs) into your /etc/rc.d directory (If using FreeBSD 4.x, install the rc_subr port and copy the run script to /usr/local/etc/rc.d/sbbs.sh instead) 3) Set up the sbbs settings: In one of /etc/rc.conf, /etc/rc.conf.local, or /etc/rc.conf.d/sbbs add the line: sbbs_enable=YES # Required to run Synchronet 4) In one of the files from step three, add appropriate lines from the following (Defaults are shown here): sbbs_flags="" # Additional command-line flags sbbs_pidfile="/var/run/sbbs.pid" # Path of pid from your .ini sbbs_dir="/sbbs/" # Root sbbs path # The rest of the sbbs_*dir derive # from this be default sbbs_ctrldir="${sbbs_dir}/ctrl/" sbbs_execdir="${sbbs_dir}/exec/" sbbs_program="${sbbs_execdir}/sbbs" # Synchronet binary sbbs_procname="${sbbs_program}" # Process name as seen by ps(1) sbbs_shell="/bin/sh" # SHELL variable sbbs_user="root" # User to START sbbs as. If this is # not root, you cannot bind low ports sbbs_group="wheel" # Group to start sbbs as 5) Start the Synchronet system service (FreeBSD 5.x+): # /etc/rc.d/sbbs start (FreeBSD 4.x and lower): # /usr/local/etc/rc.d/sbbs.sh start A note on SysOp paging: For most systems, the BBS must either have write access to the sound card via /dev/dsp, or run as root to page the SysOp. FreeBSD supports an alternative method which requires one of the following: On FreeBSD 4.x: A custom kernel with the following option in the config pseudo-device speaker On FreeBSD 5.x and higher: One of: 1) A custom kernel with teh following option in the config device speaker 2) The speaker module loaded by either: - Running ``kldload speaker'' - The line ``speaker_load="YES"'' in /boot/loader.conf /dev/speaker should be read/writeable by the user the BBS runs as. /* End of sbbscon.txt */