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 <HOSTNAME>.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 */
