Backtalk Installation Guide

Part I: Backtalk Configuration

Version 1.3.30

© 1996-2003 Jan Wolter, Steve Weiss

Prev: Introduction
Next: Part II: Compilation


The first step in installing Backtalk is to configure the programs. To do this, you unpack the distribution, cd into the distribution directory and do:

 
         ./configure <options>
 

NOTE:

  1. You'll almost certainly need some options on the configure command.
    Most options have default values appropriate for a simple installation using Backtalk accounts, but most installers will want to change at least some of them. It is possible that running configure without options will work for you, but you should scan the option list below to make sure there is nothing there you need. A summary of options can be printed by doing "./configure --help".

  2. Backtalk's configure option flags work differently than most configure scripts.
    The default flag values apply only to the first time you run configure. Later, the defaults are whatever value the flag had on the previous run. Thus, if you want to change just one option flag, you can rerun configure giving just the option to change. Everything else will retain it's previous value. If you want to start over from a clean slate, remove the config.cache file before rerunning configure.
A few options have no default values. If you don't specify them, the configure script will prompt you for values on the first run. On later runs the default values are the values you gave on the first run, so won't be prompted again. To change them, either give the flag, or remove the config.cache file.

"Mandatory" Options

A few options do not have default values, since the correct values vary too much between systems, and they are too difficult to automatically detect in any reliable fashion. If you do not specify values for these options on the configure command and there are no cached values from a previous run, then you will be prompted for values.
--htmldir=<path>
--htmlurl=<url>

HTML Directory and URL.
Backtalk uses several .html files that need to be accessible over the web. You need to specify the full path name of the directory in which they are installed, and the full URL of that directory.

For example, if you are installing Backtalk under the system's document root, you might specify:

--htmldir=/usr/local/apache/htdocs/backtalk
--htmlurl=http://my.system.com/backtalk
or if you are installing Backtalk under a user account on the system, you might specify:
--htmldir=/home/mylogin/public_html/backtalk
--htmlurl=http://my.system.com/~mylogin/backtalk

Note that --htmldir must always begin with a slash, and --htmlurl must always begin with "http://" or "https://".

--cgidir=<path>
--cgiurl=<url>

CGI-Bin Directory and URL.
Backtalk uses many cgi-bin programs that must be installed where they can be executed by the web server. You need to specify the full path name of the cgi-bin directory to use and the full URL of that directory.

For example, if you are installing Backtalk into the system's cgi-bin directory, you might specify:

--cgidir=/usr/local/apache/cgi-bin/backtalk
--cgiurl=http://my.system.com/cgi-bin/backtalk

Some systems are set up so that CGI programs can be installed in the same directories as HTML documents, with the CGI programs being identified by a file-name suffix like .cgi. In such cases your --cgidir and --cgiurl values may be the same as your --htmldir and --htmlurl values, but you should also set the --cgi-suffix=.cgi option, as described below.

Note that --cgidir must always begin with a slash, and --cgiurl must always begin with "http://" or "https://".

--httpd-id=<id>

User HTTP Server Runs As.
The HTTP server on your system runs as some particular user. Backtalk needs to know what user that is so that it can check that is it really being run by HTTP server, and so that authentication databases can be set up to be readable only by the HTTP server.

On many systems, the HTTP server runs as "nobody" (though we think it is better to set up a separate account called "www" or "http" for the HTTP server to run as). If you are running Apache, you can find out what user it is running as by looking at the User option in the Apache configuration files. Alternately you could do a ps and note what login most httpd processes are running as (there may be one running as 'root' - ignore it).

Note that if your CGI's will be running under 'suexec' or some other wrapper that causes them to be run by the owner of the file, then this should be the owner of the files, exactly the same value as the owner-id below.

You can specify the id number either by UID number, or by login name, like:

--httpd-id=65534
or
--httpd-id=nobody
Note that if you give the login name rather than the uid number, then the configure script needs to convert the name to a number. It is fairly clever about figuring out how to do this on most Unix systems, but if you are building a binary to be run on some other system, a conversion based on your build system's password database may not be correct. Use uid numbers in such cases.

--owner-id=<id>

User Backtalk Should Run As.
Ideally you should create a new Unix account for Backtalk to run under. All the conference files will be owned by this user, and Backtalk processes will (mostly) run as this user. We suggest that the name "backtalk" be used for this account, but "cfadm" is traditional for Picospan and Yapp systems.

It would be unwise to use root for this. Anything else is OK, though an account used for nothing else is best.

It can be set to the same value as --httpd-id. If you are running under suexec it must be the same. However, doing this in a non-suexec environment may weaken Backtalk's security since this would allow all cgi programs on your system to access the conference and user databases.

You can specify the id number either by UID number, or by login name, like:

--owner-id=406
or
--owner-id=backtalk
If you use the second form, the account must exist, so that the configure script can figure out its UID number. It is fairly clever about figuring out how to find the UID number on most Unix systems, but if you are building a binary to be run on some other system, a conversion based on your build system's password database may not be correct. Use uid numbers in such cases.

--owner-group=<id>

Group Backtalk Should Run As.
This is only needed if you are using Unix login ids with Backtalk, in which case a new group should be created for Backtalk to run in. Nothing else should be in this group, as all user's participation files will be readable and writable to this group. It would be reasonable to give the group the same name as the owner account.

You can enter either the group name or group id number. Names will be converted to numbers by looking them out in the system's group database.

--admin-group=<id>

Group Backtalk Admin Accounts will be in.
This is only needed if you are using Unix login ids with Backtalk, in which case it should be the GID number or name of a unix group. All Unix accounts in this group will have conference administration rights, and will be able to create, destroy and reconfigure conferences through the web interface, and will function as fairwitnesses in all conferences.

Command-line admin tools can be used only from the account defined by the 'owner_id' flag.

Directory Structure Options

There is a set of options to tell the system what to install where. Most users will find is sufficient to just use --prefix to set a root directory for Backtalk, and just let the rest default. However, you can set each directory individually.

The first two are just prefixes that are used in the default values for the others:

--prefix=<prefix>

Architecture-Independent Directory Prefix. Default= /usr/local/backtalk
Install all architecture-independent files under this (like conference data files, scripts and configuration files).

--exec-prefix=<exec-prefix>

Architecture-Dependent Directory Prefix. Default= <prefix>
Install all architecture-Dependent files (like executable binaries) under this.

The rest of the directory options designate specific directories where Backtalk files are installed, as outlined in the following table:

optiondefaultwhat's installed
--cgidir     No default            CGI programs: backtalk
--bindir     <exec-prefix>/bin     Command-line administrative commands: makeconf, decomp, btpasswd*, btvalid*, btrmuser*, btmkuser*
--libexecdir <exec-prefix>/libexec Programs usually run by other programs: btc, partutil**
--bbsdir     <prefix>/bbs          Conference data files.
--userdir    <prefix>/user         User's settings and participation files*.
--scriptdir  <prefix>/script       Backtalk scripts.
--etcdir     <prefix>/etc          Read-mostly data files owned by owner-id.
--passwddir  <prefix>/passwd       Read-mostly data files owned by httpd-id, mainly the auth database*.
--logdir     <prefix>/log          Backtalk log files.
--htmldir    No default            Images and style sheets.
--mandir     <prefix>/man          Man pages.

*  These files are only installed for systems with Backtalk accounts.
** These files are only installed for systems with Unix accounts.

Other Backtalk Configuration Options

The rest of the configure options have default values that may well work just fine for you.
--cgi-suffix=<suffix>

CGI Filename Suffix. Default= null
This is a suffix to be appended to the names of all CGI program filenames. Some servers are configured so that all CGI programs must have names ending in .cgi. If this is the case on your server, you should specify a --cgi-suffix=.cgi option.

--login=basic|form

Type of Authentication to Use. Default= basic
Backtalk can use either of two different methods to track the identity of logged in users from page to page.
--login=basic
Basic Authentication. This is the authentication method built into all browsers and http servers. In the case of Apache, authentication is actually handled by any one of several authentication modules, like mod_auth, mod_auth_dbm, mod_auth_db, etc. Users will see a pop-up box with a login form when they enter the system. The browser will automatically remember their password and resend it as needed to access future pages. It is not possible for users to log off without exiting all their browser windows.

The disadvantages of this are lack of control over the appearance of the login window, lack of a logout button, and somewhat promiscuous sending of the user's password, leading to increased vulnerability to sniffers.

--login=form
Cookie-Based Form Authentication. Backtalk will generate a login box on the main page. After users log in, a cookie will be set containing a 'session ID'. The browser will automatically send that back with all future requests. Backtalk looks the session ID from the cookie up in a session database to identify the current users. Users can log off by clicking a logout button on the screen.

This may be insecure on some servers! Cookies are passed to CGI programs in environment variables. On most Unix systems, it is possible to see the values of environment variables in other user's processes. Thus if any untrusted users can login to or install CGI programs on the server you are using, then they could potentially steal a session ID and impersonate a user.

--auth=text|db|dbm|sql|passwd|shadow

Type of Database to Authenticate From. Default= text
Backtalk users will normally be required to give a login and password before accessing Backtalk. These will be checked (by httpd) against some sort of database to see if they are correct. This option specifies what kind of database to use. If used with --login=basic your http server must have a module installed that supports this form of authentication database. With --login=form no special support from the http server is needed and any of these options can be used.

The first four options are for Backtalk accounts, maintained by Backtalk's user administration tools.

--auth=text
Logins and passwords are kept in a flat text file. This is for use with standard authentication systems like Apache's mod_auth.
--auth=db
Logins and passwords are kept in a hashed Berkeley DB database. This is for use with Apache's mod_auth_db. It gives faster authentications than the text option. You need some version of the Berkeley DB library installed on your system. Backtalk, like Apache supports versions 1, 2 and 3.
--auth=dbm
Logins and passwords are kept in a hashed DBM database. This is for use with Apache's mod_auth_dbm. It gives faster authentications than the text option. You need some DBM library (Gnu's GDBM and Berkeley DB can emulate DBM) installed on your system.
--auth=sql
Logins and passwords are kept in an SQL database. You must specify which SQL server (ie, PostgreSQL, MySQL, etc) you are using with one of the --with-* options below. There are many third-party Apache modules for doing basic authentication from an SQL database that could be used with this (mod_auth_pgsql, mod_auth_pg, mod_auth_mysql, mod_auth_msql, mod_auth_oracle, mod_auth_ora7, mod_auth_ora8, etc.). However, this is most commonly used with --login=form instead.

The last two options are for real Unix accounts. You'll need to use the standard Unix account administration tools to create and manage these accounts.

--auth=passwd
Logins and encrypted passwords are kept in the standard Unix /etc/passwd file or some other database that is readable to all users. This is for Unix systems which do not have shadow password files (a dying breed due to their security weaknesses). To authenticate from such a database with Apache, you'll need to install mod_auth_system or mod_auth_pam. (Mod_auth_external could be used, but is overkill.)
--auth=shadow
Logins and encrypted passwords are kept in the standard Unix /etc/shadow file or some other database that is readable only to root. This includes almost all modern Unix systems. To authenticate from such a database with Apache, you'll need to install mod_auth_external and pwauth. (Mod_auth_system or mod_auth_pam could be used, but only if you weaken system security significantly.)
If you implement your own authentication module, it can be selected with this option. If the module is implemented in src/auth_foo.c and incl/auth_foo.h then it can be invoked with an --auth=foo option.

--ident=tagfile|authfile|text|hash|sql|yapp

Type of Database to Store User Information In.
Default= tagfile for Backtalk accounts, authfile for Unix accounts
Backtalk needs information about each user, such as uid number, full name and home directory. (Note that uid numbers and home directories for Backtalk accounts are completely unrelated to normal Unix uid numbers and directory names - they are used only internally to Backtalk.) There are several options for where this information is stored.
--ident=tagfile
The user's home directory is generated from his login name by a standard algorithm. All other user information is stored in a file stored in that directory. This option is fast and easily maintained, but may require more disk space than the centralized database options.
--ident=authfile
All user information is stored in the same database as the authentication information. This is the only option that can be used if you are using real Unix accounts, but it can be used with text or hashed databases too. Apache will tolerate having extra information in the various authentication database, but this is not necessarily true for other HTTP servers. Used with SQL servers, this puts the identity information in the same table as the password instead of in a separate table.
--ident=text
User information is stored in a flat file similar in format to the /etc/passwd file, without the password field. This can be a slow to search if you have thousands of users.
--ident=hash
User information is stored in a hashed db or dbm file. These can be searched very quickly, but can be more difficult to maintain.
--ident=sql
User information is stored in an SQL table. The SQL server being used must be specified using one of the --with-* options below.
--ident=yapp
This is for compatibility with Yapp installations that do not use Unix accounts. The user's full name and email address is stored in Yapp-style file called 'passwd' in their home directory. The uid and gid values are stored in a file called 'id' similar to that used in the --ident=tagfile option. This is clunky and the only reason to use it is if you are running web Yapp and Backtalk on the same conference database.
If you implement your own identity module, it can be selected with this option. If the module is implemented in src/ident_bar.c and incl/ident_bar.h then it can be invoked with an --ident=bar option.

--group=text|sql|unix

Type of Database to Store Group Information In.
Default= unix for Unix accounts, sql with SQL identity databases, text otherwise
The group database gives the name and group id of the different user groups, and tells which users are in which groups. The default settings will almost always be right.
--group=unix
Use the native Unix group database, normally the /etc/group file. This can only be used if --auth=passwd or --auth=shadow has been selected, and it is the only option in that case.
--group=sql
Use two tables in the SQL database. An SQL server to use must be specified using one of the --with-* options below.
--group=text
Use a Backtalk text file whose format is similar to the unix group file. This is normally used with non-SQL Backtalk accounts.

If you don't want to do anything much with groups, you can select this option and not create the Backtalk group file. Backtalk will assume the existance of three hardcoded groups: cfadm, gradm, and user, with group ID numbers 0, 1, and 2 respectively. This will give you a tiny performance gain.

If you implement your own group module, it can be selected with this option. If the module is implemented in src/grp_baz.c then it can be invoked with an --group=baz option.

--session=none|text|sql

Type of Session Database to Use. Default= none with --login=basic or text with --login=form
If and only if you are using form logins, then Backtalk will need to maintain a session database that keeps track of all currently logged in users. Two formats are supported:
--session=text
Binary File. Sessions are recorded in a binary file, normally named <etcdir >/bt_session.
--session=sql
SQL Server Table. Sessions are recorded in an SQL table. An SQL server to use must be specified using one of the --with-* options below.
If you implement your own session module, it can be selected with this option. If the module is implemented in src/sess_baz.c then it can be invoked with an --session=bas option.

--disable-edituser
--enable-edituser

Disable User Database Editing Backtalk normally includes tools to do a variety of different kinds of user database editing, including creating and deleting accounts, changing passwords, and changing full names.

Obviously these are all disabled if you use Unix logins - Backtalk should not have access to edit the Unix /etc/passwd or /etc/shadow file. In such installations account maintainance is done through the usual Unix tools.

If you are using a pre-existing authentication database, and already have a suite of tools to maintain it, then you may not want to enable Backtalk to edit that database as well. In such cases, you should configure with the --disable-edituser option.

--disable-attachments
--enable-attachments

Disable Attachments Backtalk normally allows users to attach images and other files to their postings. These files are uploaded to the Backtalk server and maintained there, being kept as long as the response they are attached to is kept. Allowing users to post attachments, however, can eat up a lot of disk space, especially since we haven't yet implemented any kind of quotas, so disabling this feature may be a good choice for installations with limited disk space.

If attachments are disabled, users will still be able to include links and images in Backtalk postings, but they will have to get those files onto the web via some route other than Backtalk.

The attachments themselves are always stored in disk files. The attachment index will be stored in an SQL database if you have configured Backtalk with an SQL server, or in a dbm hash file otherwise.

--with-pwauth=/path/to/pwauth

Compile with the 'pwauth' authenticator Default= No
This is only used or needed if you are doing form-based logins (--login=form) with real Unix accounts (--auth=shadow). Then Backtalk will need to know the path where the pwauth program is installed so that it will be able to check the validity of passwords. The pwauth package is part of the mod_auth_external distribution.

--with-aspell
--with-ispell

Compile with the 'aspell' or 'ispell' spellchecker Default= No
If you have Kevin Atkinson's GNU Aspell program, or Geoff Kuenning's International Ispell program version 3.1.x installed on your server, Backtalk can use it to allow users to spell check their postings. GNU Aspell and International Ispell are freeware and are available from http://aspell.sourceforge.net/ and http://fmg-www.cs.ucla.edu/geoff/ispell.html respectively.

If your system seems to have both, then very likely you really have only aspell, and the thing that appears to be ispell is aspell pretending to be ispell. Aspell is probably generally to be prefered, though the foreign language support in ispell may (or may not) be better.

No other spell checkers are yet supported. In particular, ispell version 4.0 is a completely unrelated program, not a newer version of International Ispell and is not supported (and hard to find these days).

If you have and want to use aspell include the --with-aspell path. If it is installed in a directory not in your current path, do --with-aspell=/absolute/path/to/aspell. Ispell can be configured similarly.

--with-suexec

Run under suExec or cgiwrap Default= No
Many ISPs set Apache up so that all your CGI programs run as you, instead of as whatever user Apache runs as. This is typically done with a program called suExec or cgiwrap. If you are in this kind of environment, then you will need to turn on the with-suexec flag, and set both owner-id and httpd-id to your login ID.

Choosing this option weakens Backtalk's security. The file containing encrypted passwords must be readable to anyone who can log into any Unix account on the server. This is because the authentication database must be created and edited by programs running as you, but they must be readable to the httpd server, which does not run as you. Making it readable to the httpd server also makes it readable to all other users. In some cases, you may be able to improve on this, but mostly doing so requires an accommodating administrator, and if you had one, you wouldn't be running under suExec, would you?

--lastlog=backtalk|unix|none

What type of Lastlog file to Maintain? Default= backtalk
The lastlog file keeps a record of when each user logged in last. It's useful if you want to be able to expire abandoned accounts, or just want to know when someone was on last.
--lastlog=backtalk
Backtalk maintains it's own lastlog file. This can be used either with Backtalk accounts or Unix accounts (though with Unix accounts it will tell only when the last logged into Backtalk, not when they last logged into their Unix account).
--lastlog=unix
If you are using real Unix accounts, and your Unix system has a lastlog file, then you can define this to keep Backtalk's last log in the same file as the Unix last log. This way, the lastlog will tell when the user last logged in either via Backtalk or the via the normal login program.
--lastlog=none
Maintain no lastlog.

--userlevels=0|1|2

How many hierarchy levels to use in user directories? Default= 0
If you are using Backtalk accounts, then Backtalk will maintain a directory for each user under the --userdir directory (see below). This directory will contain his participation files and personal settings. If you have a very large number of users, then this directory of user directories could have a lot of entries and be slow to find specific users in. Increasing the number of intermediate directory levels improves search times. For example, if you use 2 levels, then the home directory for steve would be something like /usr/local/backtalk/user/s/t/steve. At most 2 intermediate levels are supported.

If you are using real Unix accounts, then ignore this - the user's normal home directory is used instead.

--with-picospan
--with-yapp
--with-yapp3

Be Picospan or Yapp Compatible? Default= neither set
Picospan is a command-line oriented conferencing system developed by Marcus Watts. It was marketed by NETI until NETI went broke. Yapp 2.3 is a clone of Picospan developed by Dave Thaler. Yapp 3.0 is a web based version of that. Backtalk can be compatible with either one, so that the same conferences can be read either through Backtalk or through Picospan or Yapp. Setting these flags ensures that Backtalk will be strictly compatible with the named conferencing system. You can't have more than one, as they are not completely compatible with each other.

Don't enable these unless you really mean to use Backtalk with Yapp or Picospan - the native file format is better.

The --with-picospan and --with-yapp options only really make sense with the --auth=passwd or --auth=shadow options and real Unix accounts. Yapp 3.0 can be configured to use non-unix accounts, in which case it should be used with the --auth=text and --ident=yapp options.

--with-pgsql
--with-mysql
--with-msql

Use an SQL Server? Default= none

Options are being added to Backtalk to enable to keep some of it's databases, especially user databases, in an SQL database. At this time, only the PostgreSQL and MySQL options have been tested. The msql option is not even completely written and will not work. We hope to add Sybase and Oracle options in the future.

Important Note on Configuring SQL Servers:
To be able to compile and link Backtalk with the header files and libraries for your SQL server, it may be necessary to explicitly give the path names where the headers and libraries reside. This is done by setting the CPPFLAGS and LDFLAGS environment variables.

The syntax for doing this differs in different shells. If you have a borne-type shell, you might do:

    CPPFLAGS=-I/usr/local/include/mysql LDFLAGS=-L/usr/local/lib/mysql \
        ./configure --with-mysql ...  
or if your system has the 'env' program, you could do:
    env CPPFLAGS=-I/usr/local/include/mysql LDFLAGS=-L/usr/local/lib/mysql \
        ./configure --with-mysql ...  
The path names above are from a FreeBSD system with MySQL. They may be different on your system.

For msql installations, the path names will usually be /usr/local/Hughes/include and /usr/local/Hughes/lib respectively.

--lock=fcntl|flock|lockf|tmpfile|any

What type of Locking to Use? Default= any
Normally the configure script will choose the type of file locking to use on your Unix system. If you are sharing conference files with Picospan or Yapp, however, then it is important that you use the same locking protocol as they do. Since they can be built with different locking protocols, you may need to explicitly define which locking protocol to use. Options are:
--lock=any
Let the configure script choose a locking protocol.
--lock=fcntl
Use the fcntl() call to lock files.
--lock=flock
Use the flock() call to lock files.
--lock=lockf
Use the lockf() call to lock files.
--lock=tmpfile
Create a temp file to indicate that a file is locked. The --lock=tmpfile locking protocol is compatible with Yapp's lock-file protocol. It has not been tested against Picospan's.

--disable-trap-crash
--enable-trap-crash

By default when Backtalk detects a software error that would cause a core dump, it instead tries to display a detailed error page describing the error. This is usually more useful, but if you'd like the core file instead, you can disable this feature with this flag. Disabling it may be a minor security hazard on some systems where core dumps are publicly readable, since those core dumps may contain sensitive data.

--enable-exec
--disable-exec

This option is only for use with Unix login accounts. If enabled, it becomes possible for users to directly execute the backtalk cgi program, and be recognized based on their uid number. This is mainly useful if Fronttalk is being run on the same server as Backtalk, since it enables Fronttalk to directly execute Backtalk instead of accessing it though the http server, thus eliminating the need for users already logged into the system to relogin to run Backtalk.

--disable-dynaload
--enable-dynaload

This option is now mostly useless, as only very small parts of the program are dynamically loaded even if it is enabled. It may not compile successfully on some versions of Unix.

Everytime you click a link or button while using Backtalk, the Backtalk program must be loaded and run from scratch (this is a problem common to almost all CGI programs). This means that loading fast is more important for Backtalk than for many other programs. If Backtalk is configured with the --enable-dynaload directive, then some of the less commonly used parts of the program will be built as shared libraries, and only linked in on-demand only if they are needed. This makes the program a bit smaller and a bit faster to load.

Low-Level Configuration Options

Not all Backtalk configuration options are settable from the "./configure" utility. For unusual configurations, you may want to set some lower-level options by manually editting the incl/config.h or incl/common.h files. Since incl/config.h is overwritten every time you run "./configure" this isn't really a great place to put local customizations. So "incl/config.h" includes "incl/localconfig.h", which exists solely as a from which to alter low-level settings.

These instructions will not give extensive details on the different low-level options. Lots of comments exist in the incl/config.h file, and most sites will never need any of these. We will list a few so you know they exist. Several of these may need to be changed when integrating with a foreign authentication system.

MAX_LOGIN_LEN
Defines the number maximum number of characters allowed in a user login name.
AUTH_FILE
Defines the location of a flat mod_auth-style htpasswd file.
AUTH_DBM
Defines the location of a hash mod_auth_db or mod_auth_dbm-style password file.
AUTO_CREATE_DIR
If defined, Backtalk will create a home directory for any user who hasn't got one. If accounts were created by another program, then home directories are likely missing.
SESSION_COOKIE
Defines the name of the cookie that contains the session ID.
SESSION_ID_LEN
Maximum size of a session ID. Defined in incl/sess.h. Changing this won't make Backtalk make larger session IDs, but if you are using session IDs generated by a different program, it will make Backtalk able to read them.

Prev: Introduction
Next: Part II: Compilation