		README for G0LGS's XFBB TELETEXT SERVERS
		----------------------------------------

COPYRIGHT

This software is Copyright (c) 2000 - 2005 by Stewart Wilkinson G0LGS.

Distribution and use of this software is permitted provided that all
copies retain the above copyright notice and the Warranty disclaimer below

WARRANTY

THIS SOFTWARE IS PROVIDED BY THE AUTHOR `AS IS' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

IMPORTANT

Please ensure you read the whole of this document before using the
programs.


INTRODUCTION
------------

These TELETEXT servers are intended for use with XFBB 7.01 and later. The
set of programs includes programs for use at the BBS prompt, ones that
respond to Messages sent to them and a WEB CGI interface.

These programs are based on similar programs written by VK5ASF and GM7HHB.

FBBTEXT
-------

This is the PG program for BBS user to display any available TText pages.
It can normally be invoked at the BBS in prompt using any of the following
commands:

	PG fbbtext
	PG tt
	fbbtext
	tt	

REQTT
-----

REQTT is a FBB Message server which reponds to any SP message sent to it
by any user (local or remote), it returns one or more TText pages as a
message addressed to the originator (at the BBS they sent the request
from). Messages must be sent using the format

	SP REQTT [@ GB7xxx]
	Request			<- Anything will do

	100			<- Page 100
	INDEX			<- The Index Page (whichever that is)
	HELP			<- The Help Page

	---
	Any text after a line of 3 or more dashes will be ignored.

	/EX

Any / All requests for a non-existant page will cause the 'nopage' page
(or its default to be sent).

Note: Multiple pages can be requested in a single message, but the maximum
number that will be return will depend on the configuration set by the
SYSOP.


TTPUD
-----

TTUPD is a FBB Message server, which can be used by the SYSOP or anyone he
authorises to obtain RAW TText pages from the system and to update those
pages or add new pages to the server. The Program will ONLY respond to
message from Authorised users and can only be used to manage page numbers
greater than 100. (Pages <= 100 can only be changed directly by the SYSOP)

The TTUP server will accept updated pages using the following format:
 
	SP TTUPD
	UPDATE			<- Anything will do

	There can be any text here.

	PAGE_START 599
 
	All text between PAGE_START and PAGE_END will be included in the page.
	This is the third line of page page 599
 
	PAGE_END

	Any text here will be ignored.

	/EX

Note: Multiple updates can be included in a single message.

The TTUPD server will send you the RAW TEXT page including all TTEXT
VARIABLES in response to the 'REQUEST' command:

	SP TTUPD
	REQUEST			<- Anything will do

	There can be any text here.

	REQUEST 599

	Any text here will be ignored.

	/EX

Note: Multiple pages can be requested in a single message.

You can (if you wish) mix PAGE UPDATE's & PAGE REQUEST's in the same
message.

At present there is NO LIMIT to the number of UPDATE's / REQUEST's you may
use in each message sent to the server, however this may change in future
versions.

WEBTT
----

WEBTT is WEB CGI program, it allows a user to display a requested page in
their web browser, it can be used to display either specially formatted
web (.htm) versions of the pages (in preference) or the Text versions as
server by FBBTEXT and REQTT.

The Sysop is required to define at least one limit on the range of pages
that are available via the WEB interface, failure to define any will
result in all requests showing the 'nopage' page (or its default).

For the WEB CGI to work the user that your WEB server runs as (often
'nobody') needs read access to the TText files, this can be done in
various ways and will depend on the Sysops own preference.

WARNING: WEBTT does NOT do logging of its own activities, so if you want
to see what its doing, you will need to make sure that your WEB server has
suitable logging enabled.

INSTALLATION
------------

There are a number of installation options available, the ones you need
will depend on which servers you are going to make available on your
system.

If you have the Source Distribution:

	Before you do anything ensure that the install path information
	in the Makefile and in config.h match your system.

If you have a Binary Only Distribution:

	The Binary Distribution should contain Statically linked programs,
	if you want a dynamically linked set of programs you will need to
	obtain the Source Distribution.

	Rename Makefile.bin to Makefile

	Ensure that the install path information in the Makefile
	match your system.


To install the main programs (FBBTEXT, REQTT and TTUPD)

	make install

To install the default config file:

	make install-cfg

To install the WEB CGI interface:

	make install-cgi

To install the sample TText pages:

	make install-samp

To install ALL of the above:

	make install-all

Note: If you are installing these servers for the first time it may be
necessary to restart XFBB so that it can use the programs. (The sysop
command /R normally does this).


CONFIGURATION
-------------

All the programs need read access to the fbb.conf file, by default the
programs expect to find this at /etc/ax25/fbb.conf, but this can be
overridden by setting the FBBCONF environment variable. (ie: Adding
'export FBBCONF="/home/xfbb/fbb.conf"' into your XFBB Startup script).

The following settings are used from fbb.conf:

Required:

	impo = /var/ax25/fbb/mail/mail.in	(FBB's 'mail.in')

	data = /var/ax25/fbb/			(FBB Data folder)

Optional (but desired):

	conf = /etc/ax25/fbb/			(ttext.cfg should be here)

	call = GB7xxx.#nn.GBR.EU		(BBS Callsign)

	ssid = 0				(BBS SSID)

	name = Stewart				(Sysop's name)

	city = Cheltenham			(BBS Location)

	qral = IO81WV				(BBS QRA / QTH)

	zipc = GL51				(BBS Postcode)

Note: If the programs fail to find fbb.conf, or fbb.conf does not specify
values that the programs require then the programs may not work correctly.

If you are going to use the Message Servers (REQTT or TTUPD) You will need
to make a couple of changes to the Servers Section of your fbb.conf:

for REQTT add a line like:

server = REQTT reqtt		TTEXT Server

for TTUPD add a line like:

server = TTUPD ttupd            TTEXT Update Server



All other configuration options are in the 'ttext.cfg' file, this file is
normally located in the same directory as 'fbb.conf' (ie: /etc/ax25/fbb/)
but if your fbb.conf defines an alternative location ('conf =' line) then
ALL the programs will look in this location instead.

Note: All the programs have default values for all 'ttext.cfg' settings
that were defined at compile time (see the Makefile and config.h in the
source).

A typical ttext.cfg might be:

;
; Config file for G0LGS's FBB TTEXT Server(s).
;
; Page number for the index (without .TT): 
; Default = 100
index=100
;
; Maximum number of pages allowed in any REQTT message
; Default = 10
maxpages=10
;
; Maximum number of lines sent in one message
; (should sort out the large pages problem!)
; Default = 30
linemax=30
;
; Folder for TT files
; Default defined in config.h
ttdir=/usr/local/fbb/tt
;
; Information to be tagged on to report
; Default = NONE
info=/usr/local/fbb/tt/thanks.tt
;
; Up to 200 User definable page labels. Format DESCRIPTION,PAGE NUMBER
; REQTT & FBBTEST will swap description for page number
; The first entry is usually INDEX = 100 (This is Default if non specified)
user=INDEX,100
;
; FBBTEXT config commands
; Prompt for fbbtext
; Default defined in config.h
prompt="($=): $O Text : F,B(ye),INDEX,I(nfo),?,###>"
;
; First page to display
; Default = 100
firstpage=100
;
; No page indicates what "page does not exist" file to use
; If this page does not exist will use inbuilt Default (as per config.h).
; Default = nopage - 
nopage=nopage
;
; Up to 200 Page Ranges Available via Web (Default = None)
webok=100,100,110,110,115,115,200,200,300,300
;
; Who's allowed to do update pages using TTUPD
; Only pages > 100 can be updated
; Max 10 Callsigns. (Default = EMPTY)
;updates=
;
; Log file (Default defined in config,h as /var/ax25/fbb/log/ttext)
; use 'logfile=' to disable all logging.
logfile=/var/ax25/fbb/log/ttext
;
; Format of Date / Time in Log (see 'man strftime' for options).
logtime="%b %d %Y %H:%M:%S"
;


VARIABLES on TTEXT PAGES
------------------------
 
All TText pages served by REQTT, WEBTT or FBBTEXT can use the following
variables in the page definitions (some of these are the same as the FBB
internal equivalents):

	%A :	App Name (Left Justifed 9 Chars)
	%O :	Sysop Callsign
	%V :	TText Version Number
	%% :	The '%' character

	$b :	User Zip		(for FBBTEXT only)
	$c :	BBS City
	$d :	Date DD-MM-YYYY
	$h :	User HomeBBS		(for FBBTEXT only)
	$o :	BBS SSID
	$u :	Remote BBS or IP
	$z :	BBS ZIP
	$A :	App Name (Right Justified 9 Chars)
	$H :	Time HH:MM
	$I :	Users Name		(for FBBTEXT only)
	$O :	BBS Callsign
	$U :	User Callsign / Hostname
	$W :	CR\LF
	$? :	BBS QRA / QTH
	$@ :	TText Page number (or name)
	$$ :	The '$' character
	$= :	TText Level Number (number of calls this session).

	$<Filename.Ext:		}
	$<"File Name.Ext"	} Insert another TText File

Use of undefined variables (ie: $I in REQTT or WEBTT) will display the
NULL string ("").

Use of any other % or $ options will normally result in the program
generating the text exactly as entered in the TText file, However XFBB
will then use its internal values when it processes the output before
passing it to the user (FFBTEXT Only).

FBB VARIABLES
-------------

Pages served by FBBTEXT may also use FBB's internal variables, to do this
use '%%c' or '$$c' in the TText page.

Note: Using FBB's internal variables does not work when the pages are
requested using either REQTT or WEBTT. It is therefore suggested you use
only the values shown in the table above.
	
FREQUENTLY ASKED QUESTIONS

Q. Can I use the CGI programs in a folder other than /home/httpd/cgi-bin ?

A. Yes, change the CGIBIN path in the Makefile and do 'make install-cgi'
   to install the CGI program (WEBTT).


Q. Why do I get the message install: invalid user `nobody' when I try to
   install the CGI (WEBTT) program ?

A. This is becase the Supplied Makefile assumes that the CGI program (WEBBT) 
   has to be installed for a user called 'nobody' and your system is
   configured to use some other username. Edit the Makefile and change
   all occurances of 'nobody' to whatever 'user' your Web Server requires.

   I recommend that the CGI interface NOT be installed / run as 'root' as
   this could lead to all sorts of security problems.


Q. Why does XFBB generate the message 'error starting REQTT' or 'error
starting TTUPD' whenever someone sends message to the servers ?.

A. There are a number of factors that can cause this, things to check for
include:

	That you have installed the REQTT and TTUPD programs in the
	correct folder (typically: /usr/lib/fbb/server), and that they
	are marked executable (ie: 'chmod 555 reqtt ttupd').

	That your fbb.conf file exists in /etc/ax25 or you have set
	the FBBCONF environment variable to tell the system where to
	find fbb.conf (See the CONFIGURATION section above).

	That your fbb.conf has all the entries noted as required (see
	the CONFIGURATION section above).

	That the folder defined in the 'impo = xxx' line in fbb.conf
	exists and is writable by XFBB (and hence by REQTT and TTUPD).

	The ttext Log file (as defined in ttext.cfg) may contain
	information to help identify the casue of a problem.

-----
Stewart G0LGS
Sysop GB7LGS
Dec 2001
