Backtalk Installation Guide

Part I: Backtalk Configuration

Version 1.0.9

© 1996-2000 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://".

--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://".

--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).

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.

It can be set to the same value as --httpd-id. If you are running under suexec it has to be the same. However, doing this 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
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-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.

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.

--auth=text|db|dbm|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.

The first three 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.

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.)

--ident=tagfile|authfile|text|hash

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 Backtalk accounts too. Apache will tolerate having extra information in the various authentication database, but this is not necessarily true for other HTTP servers.
--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 store in a hashed db or dbm file. These can be searched very quickly, but can be more difficult to maintain.

--makeacct=open|validate|closed

Who can create new accounts? Default= open
If you are using Backtalk accounts, this option controls who can create new accounts using the makeacct program. This option is ignored if you are using Unix accounts.
--makeacct=open
Anyone can fill out a form on the web page to create themselves an account, which is created immediately and gives immediate access to the conferences.
--makeacct=validate
Anyone can fill out the form on the web page to create themselves an account, but the account is created in an 'unvalidated' state and cannot be used until a system administrator has 'validated' it.
--makeacct=closed
Only system administrators can fill out the account creation form and create new accounts with it.

--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

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. 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 both, 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.

These options only really make sense with the --auth=passwd or --auth=shadow options and real Unix accounts.

--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-debug
--disable-debug

This flag enables some features which make it easier to run the Backtalk program under a debugger like `gdb', but also severely undermines Backtalk security. The debug option should be disabled on all production installations. It is disabled by default. For more information about this option, see the comments in `incl/config.h'.

Note: Unlike all other Backtalk configure options, this one is not sticky. It always defaults off, even if you had it turned on the last time you ran configure.

Directory Structure Options

There is a set of options to tell the system what to install where. 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, confutil, makeacct*
--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 Users 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 HTML pages.
--mandir <prefix>/man Man pages (actually, there aren't any yet).

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

Prev: Introduction
Next: Part II: Compilation