Welcome to TeamSCOPE.
TeamSCOPE is designed to facilitate primarily asynchronous communication among members of geographically distributed teams through a web interface. It provides server-based file management, message boards, calendar management, resource reservation, and other services.
This manual will guide you through installation, configuration, and maintenance of the TeamSCOPE system.
TeamSCOPE and this manual were written by Ben Pfaff pfaffben@msu.edu.
You have a few choices for setting up TeamSCOPE:
To compile TeamSCOPE yourself, follow the entire procedure described in the sections below.
To install this way, use dpkg to install the TeamSCOPE package,
then continue from section Configuration.
Note that currently TeamSCOPE is recommended for use under Debian GNU/Linux only. Other distributions may work out-of-the-box, but some porting effort may be required. Other OSes will almost certainly require porting.
Before compiling, make sure that you have the following prerequisite programs and libraries installed on your system.
Obtain at `ftp.debian.org' in `/debian/dists/potato/main/source/libs' as `libgd-gif_1.3.orig.tar.gz'. You must not use a version newer than 1.3, as these newer versions support only PNG output, not GIF.
Available from postgresql.org. TeamSCOPE has been tested with versions 6.5.3 and 7.1.2. Users of version 6.5.x may need to apply a patch in order for database backups to function correctly (see section Configuration).
Available from perl.com. TeamSCOPE has been tested with versions 5.004.04 and 5.005.03.
Jikes (preferred) and Sun's Java compiler are known to properly compile TeamSCOPE's Java code. GNU Compiler for Java (gcj) did not work the last time it was tried.
GNU Texinfo is used in producing the online and printable versions of the TeamSCOPE manuals.
TeX, as well as dvips and pdftex, are necessary to
produce printable versions of the TeamSCOPE manuals.
Available from apache.org. Versions known to work with TeamSCOPE include 1.3.9 and 1.3.20.
Available from ftp.uu.net.
Available from exim.org.
Unpack the source distribution into an appropriate directory. Change directory into the source tree root directory.
Make a build directory and change directory into it with the commands `mkdir build; cd build'.
Configure the source distribution with the `configure' program. Autoconf will inspect your system for libraries and include files.
You may pass command-line options to configure. For a list of
options, use the command `../configure --help'.
Example 1: To configure TeamSCOPE to use the default GNU directory structure, use the following command:
../configure
Example 2: To configure TeamSCOPE to use an FSSTND- and FHS-compliant directory structure, use the following command:
../configure --prefix=/usr --localstatedir=/var/lib \
--libexecdir=/usr/lib --sysconfdir=/etc
Edit `scope.conf' to adapt the directory names and filenames to those used by the local system and web server.
Please note: Don't skip this step. TeamSCOPE interacts closely with other programs. It must be configured properly. Read and verify each setting in this file before compiling TeamSCOPE.
Run make: `make'. Wait for the compile to complete.
Compiling TeamSCOPE on a Debian system in order to make a Debian package out of it is pretty easy. TeamSCOPE is known to compile "clean" under at least the potato and sid distributions. Just follow these steps instead of those listed above in order to make a Debian package:
Unpack the source distribution into an appropriate directory. Change directory into the source tree root directory.
Check `debian/control' for the list of "build dependencies".
This is a line that begins with Build-Depends: and contains a
list of most of the Debian packages needed to compile TeamSCOPE.
Install any packages listed here that aren't already installed. Also
make sure that `gcc', `make', `dpkg-dev', `fakeroot', and `libc6-dev'
are installed.
Run `dpkg-buildpackage -rfakeroot'.
You should now have a `.deb' package for your machine in the directory above the source tree.
Become root, and install TeamSCOPE: `make install'.
Create a user and group, each named `scope', to own the TeamSCOPE
database, for instance using system utilities such as useradd and
groupadd.
Create an empty TeamSCOPE password file; for instance, with the command `touch /etc/scope/passwd'. The password file should be owned by root; it only needs read and write permission for root. Future versions of TeamSCOPE may be redesigned to incorporate the password into the database.
(Optional) If you plan to use TeamSCOPE's web-based administrative features, you should perform this step; otherwise, it is recommended, but not required. Create a script that causes your web server and mail server to reload their configurations and put it in the TeamSCOPE configuration directory under the name `reload'; for instance, `/etc/scope/reload'. It should be marked executable, for instance using `chmod a+x reload'. Sample contents:
#! /bin/sh -e if test -x /etc/init.d/apache; then /etc/init.d/apache reload; fi if test -x /etc/init.d/exim; then /etc/init.d/exim reload; fi
The `scope-db' configuration tool will automatically run the `reload' script at appropriate times. If no such script exists, `scope-db' will advise you to manually restart these services.
Generate TeamSCOPE's timezones file with `scope-db init timezones'.
Create the TeamSCOPE database with the command `scope-db create'.
TeamSCOPE requires some commands to be run periodically. These are the following:
scope-db sync-mail
This command operates the TeamSCOPE message board to email gateway. It is optimized to use little CPU time. It should be run often; for instance, every 6 minutes. See section Scheduled maintenance, for more details.
scope-db hourly-mail
This command sends TeamSCOPE activity update emails to users who have requested them. It should be run once an hour. See section Scheduled maintenance, for more information.
scope-db daily-maint
This command performs TeamSCOPE daily maintenance chores, including backing up the TeamSCOPE database and cleaning up old session data files. It should be run once a day. See section Scheduled maintenance, for more information.
Here are sample lines for `crontab' that implement the above,
assuming that scope-db is installed in `/usr/sbin':
0,8,16,24,32,40,48,54 * * * * root /usr/sbin/scope-db sync-mail 5 * * * * root /usr/sbin/scope-db hourly-mail 7 4 * * * root /usr/sbin/scope-db daily-maint
Install scope-chat, the TeamSCOPE chat server. For more
information, see section Chat server.
After TeamSCOPE is installed, it must be configured. The steps below are the same whether TeamSCOPE is installed from a binary package or by hand.
Configure Apache for use with TeamSCOPE. You can do this with
scope-db or by hand:
scope-db
Run the command `scope-db init apache'. This will edit a Apache configuration file, typically `/etc/apache/httpd.conf', adding the line `Include /etc/scope/apache.conf', or similar, to it.
Add the line `Include /etc/scope/apache.conf', replacing the given filename with the one specified at compilation time.
At any rate, make sure that `AddHandler cgi-script .cgi' appears
somewhere in your Apache configuration files. scope-db will not
add this for you, so be sure to do it yourself.
If you wish to use TeamSCOPE's "team site" feature, then you should also enable server-parsed HTML documents by making sure that Apache is set up as follows:
`AddType text/html .shtml' and `AddHandler server-parsed .shtml' appear in an Apache configuration file, typically `/etc/apache/srm.conf'.
Module mod_include is loaded from an Apache configuration file
with a statement such as this:
LoadModule includes_module /usr/lib/apache/1.3/mod_include.so
Depending on your Apache setup, you may also need to add a line to `httpd.conf' something like this:
DirectoryIndex index.shtml index.html
In order to enable TeamSCOPE's email to message board gateway, your mail
server must be configured to pass messages to
scope-gw@mail.domain to scope-db received-mail on
standard input.
If you are using Exim as your mail server, you can use the command `scope-db init exim' to automatically set this up. (This also allows TeamSCOPE's email recording features to be usefully enabled.) Otherwise, configure your mail server for this by hand.
TeamSCOPE can automatically edit your email `/etc/aliases' file when users and groups are added and deleted. To enable this feature, use the command `scope-db init aliases'.
At this point, TeamSCOPE setup is almost complete. Before proceeding,
create some teams and users. You can use scope-db addgroup and
scope-db adduser. See section User administration, for more details.
After you've created some teams and users belonging to them, synchronize the TeamSCOPE configuration files with `scope-db update'.
If you didn't create a `reload' script as recommended above (see section Installation), restart Apache. If you're using TeamSCOPE's email recording features, restart Exim as well.
|
For example: Under Debian GNU/Linux, use the following command
to restart Apache: |
(Optional) If you plan to use TeamSCOPE's web-based administrative features, you must perform this step; otherwise, do not. Put a list of system administrators in the TeamSCOPE configuration directory (such as `/etc/scope') in a file named `admins'. These system administrators will be able to do potentially dangerous operations such as create and remove arbitrary user and group accounts, so put only trusted users in this list. List the system adminstrators' usernames, one per line. Comments in this file are introduced with `#' and extend to the end of the line.
If you want to record FTP activity as well as web activity in TeamSCOPE's database, install a TeamSCOPE-enabled version of ProFTPd. The file `proftpd_1.2.0pre10-2.0potato2.patch' in the TeamSCOPE source distribution contains both the necessary patch to ProFTPd to enable this feature and the instructions for doing it. (A pre-patched Debian binary package is also available.)
If you're using PostgreSQL version 6.5.x instead of 7.0 or later,
apply the patch in `postgresql-6.5.3.patch' and recompile and
reinstall at least the pg_dump program. You can try it without
this patch, but PostgreSQL database backups of the TeamSCOPE database
may fail without it. (A pre-patched Debian binary package is also
available.)
TeamSCOPE is now up and running. To test it out, point a web browser to
http://server/scope, where server is the TeamSCOPE
server's hostname.
TeamSCOPE administration and maintenance is performed with the
scope-db utility. You can get a summary of scope-db's
functionality by typing the command `scope-db help'.
`scope-db' must be run as root for most actions.
The general syntax for `scope-db' usage is
scope-db command argument...
Only one command may be used with each invocation of `scope-db', although commands may have multiple arguments.
In the descriptions below, the following typographical conventions are used:
foo
Invariant text such as command and option names.
Text that varies. The command description should say what should be supplied.
[...]
Square brackets denote optional arguments.
The following sections go into detail on usage of `scope-db' options.
These commands are used to maintain the TeamSCOPE database. Some of these commands have simple equivalents in terms of database operations, but they are provided as part of `scope-db' for convenience.
create
Creates the TeamSCOPE database if it does not already exist. This should be performed as part of the TeamSCOPE installation procedure.
remove
Deletes the TeamSCOPE database. Please note: This will cause all data to be lost! Be sure to have a backup copy of the database before running this operation.
dump dump
Writes a snapshot of the TeamSCOPE database contents to file dump. Any existing file by that name will be truncated. Please note: Ordinary users should not be allowed to view database backups, since they may contain private information.
restore dump
Restore the state of the TeamSCOPE database from snapshot file dump. You must first remove the database with `scope-db remove'.
upgrade
Upgrades the TeamSCOPE database in place to a newer version. This should be performed each time a new TeamSCOPE version is installed. (Packaged versions of TeamSCOPE perform this upgrade automatically.)
These commands are used to maintain the TeamSCOPE configuration files and configuration files belonging to other programs that TeamSCOPE updates.
There is a simple rule that TeamSCOPE uses for updating configuration files that belong to other programs: if you have not told `scope-db' to modify a configuration file, it won't. (Packaged versions of TeamSCOPE enable some of these features automatically.)
init function
Enable or initialize the specified function. The following values for function are currently defined:
apache
Enables generation of the TeamSCOPE Apache configuration file. Also
edits Apache's httpd.conf, idempotently adding an Include command
referring to the TeamSCOPE Apache configuration file.
Does not actually generate the TeamSCOPE Apache configuration file. To
do so, see update below.
exim
Enables modification of Exim's main configuration file and modifies that file idempotently to add comment markers indicating that fact.
Does not fill in the Exim configuration commands between the comment
markers. To do so, see update below.
aliases
Enables modification of the mailer aliases file and modifies the aliases file idempotently, adding comment markers indicating that the aliases file may be modified by TeamSCOPE.
Does not fill in the aliases between the comment markers. To do so, see
update below.
timezones
Generates the TeamSCOPE timezones file from a collection of system files and directories. This command should be executed once at installation time.
`scope-db update' should normally be run after any init
command.
uninit function
Disable or uninitialize the specified function, where
function is one of the values listed above for init.
`scope-db update' should normally be run after any
uninit command.
update
Updates configuration files that have been enabled with the
corresponding init command. After this command is executed,
typically the system web server and mail server should be instructed to
reload their configuration files. If a `reload' script exists,
`scope-db' runs it automatically (see section Installation).
Otherwise, the system administrator should do the same things by hand:
If updating of Apache configuration files is enabled, then Apache should be restarted (or made to reload its configuration) to make changes take effect.
|
For example: Under Debian GNU/Linux, use the following command
to cause Apache to reload its configuration: |
If updating of Exim configuration files is enabled, then Exim should be restarted (or made to reload its configuration) to make changes take effect.
|
For example: Under Debian GNU/Linux, use the following command
to cause Exim to reload its configuration: |
If updating of the mail aliases file is enabled and the system mail transfer agent (MTA) will not automatically notice this fact, then it should be notified of changes in an MTA-specific manner.
|
For example: Using the `sendmail' MTA, the appropriate command
is |
These commands are used to add and remove users and workgroups (teams).
These commands can also be performed through the TeamSCOPE web
interface; for more information, see the documentation for
addgroup below.
|
Many of the following commands require Apache or Exim to be restarted
after they are executed. If you have written a `reload' script,
this will be done automatically (see section Installation). Otherwise, it
must be done by hand. Under Debian GNU/Linux, use the command
|
addgroup [group [fullname]]
Creates a new system group and TeamSCOPE workgroup. group is the short name of the group and fullname is the full name of the group. group is limited to at most 8 characters drawn from the set of uppercase and lowercase letters, digits, hyphen (`-'), and underscore (`_'). fullname may be any length and it may contain spaces and special characters, but depending on your shell you may have to enclose in quotes a full name that contain spaces or special characters.
Note that TeamSCOPE has one special group, admin. If you create
a group by this name and add users to it, those users can perform most
TeamSCOPE administrative tasks from the TeamSCOPE web interface. As a
result, you should only add users you trust to this group, if you create
it. For more information on how to administer TeamSCOPE through the web
interface, see the TeamSCOPE Tutorial and Reference manual.
After adding a group, run `scope-db update' to update TeamSCOPE and related configuration files, then restart Apache and Exim as appropriate. See section Configuration management, for more information.
adduser [group [user [fullname [email]]]]
Creates a new system user and TeamSCOPE account within an existing workgroup. The variables have the following meanings:
Workgroup name. Users may belong to multiple groups but only one group
may be specified on the adduser command.
Username. Same restrictions as group name. user may omitted; if it is, `scope-db' will generate an available, valid username based on fullname.
User's full name, first name before last name. Same qualifications as group full name above.
User's upstream email address, for forwarding of email received by this server on the user's behalf. If email should be retained without forwarding, omit this field.
Note that user and email may be omitted. You must still
supply an empty argument. Under most UNIX shells this can be done with
a pair of single quotes (`"'). Arguments containing spaces must
also be quoted. For instance, the command `scope-db adduser admin
" 'John Q. Smith' "' supplies admin for group, John
Q. Smith for fullname, and omits user and email.
New user accounts are disabled by default. Use the mail command
to enable new accounts.
After adding a user account, run `scope-db update' to update TeamSCOPE and related configuration files, then restart Apache and Exim as appropriate. See section Configuration management, for more information.
mail [--no-reset] user
When a new account is added to the system, it is disabled by default. This command performs the following actions for the specified account:
Sets the account password randomly. If --no-reset is specified
and the account already has a password, then this step is skipped.
Sends an email to the user informing him or her of its existence and, if it was set in the step above, the account's password.
Enables the account, unless the account is locked (see lock
below).
Besides enabling new users' accounts, this command may also be used to reset the accounts of users who have forgotten their passwords.
mail --pending
Equivalent to mail --no-reset user executed for each user
on the system whose account has not yet been enabled.
deluser lusers...
Removes the TeamSCOPE and system accounts of lusers. Any number of lusers may be specified. Does not delete lusers' home directories or their contents; this must be done by hand.
After removing a user account, run `scope-db update' to update TeamSCOPE and related configuration files, then restart Apache and Exim as appropriate. See section Configuration management, for more information.
delgroup groups...
Removes the TeamSCOPE and system accounts for groups. Any number of groups may be specified. Does not delete the group's shared directory or its contents; this must be done by hand.
After removing a group, run `scope-db update' to update TeamSCOPE and related configuration files, then restart Apache and Exim as appropriate. See section Configuration management, for more information.
lock users...
unlock users...
Locks (or unlocks) the TeamSCOPE and UNIX user account for users. A user whose account is locked cannot log in to TeamSCOPE or use the server's other network services such as FTP or Telnet sessions.
addusertogroup [user [group]]
deluserfromgroup [user [group]]
Adds or removes user to/from TeamSCOPE and Unix system groups named group.
Use the mail command to notify the user of additional group
membership status.
After adding a user to or removing a user from a group, run `scope-db update' to update TeamSCOPE and related configuration files, then restart Apache and Exim as appropriate. See section Configuration management, for more information.
email [user [email]]
Sets the upstream email address for user to email. If email is an empty string then mail for user is queued locally on the server.
fullname [user [fullname]]
Sets the full name for user to fullname.
batch < file
Adds a number of users and groups at once as specified on stdin,
which should normally be redirected from a file. Lines in the file are
of two types:
Adds a new group with the specified name.
Must follow a line of the previous type. Adds a new user in group with full name fullname and email address email. A username is generated automatically.
The file may also contain blank lines. Comments are introduced by an octothorpe (`#').
This command is not yet implemented as of TeamSCOPE 0.9.13.
info [user]
Displays on stdout information about the specified user, or about all users if no username is given.
This command is not yet implemented as of TeamSCOPE 0.9.13.
The following commands are normally invoked on a daily basis from a system crontab, but they may also be run by hand.
daily-backup
Dumps a snapshot of the TeamSCOPE database into the backup directory set at compilation time. The old snapshot is renamed with a numeric extension.
The snapshot is in the format used by the restore command
(see section Database maintenance, for more information).
TeamSCOPE keeps a limited number of old backups; by default, 30. Backups older than this are removed automatically.
daily-cleanup
Removes stale session-data files.
daily-maint
Runs the above maintenance procedures in sequence.
hourly-mail
Users can request period email updates on changes to their team workspace. This command causes these mails to be sent. It should be run by a cron job on an hourly basis.
sync-mail
Users can request individual emails for each message board post. This command causes these emails to be sent. It should be run by a cron job often; for instance, every 5 minutes. This command is designed to cause as little CPU and disk load as possible, so it should possible to run it often even on a relatively busy system.
These commands are informational in nature. Root privilege is not required to run these commands.
help
Displays a summary of commands and their meanings.
version
Displays the TeamSCOPE version, copyright, and warranty disclaimer.
To temporarily disable access to TeamSCOPE (for instance, during upgrades or maintenance), create a file named `shut' in the TeamSCOPE configuration directory. You can put a message in the file, which will be sent to users who attempt to use TeamSCOPE while it is disabled.
To re-enable access to TeamSCOPE, delete `shut'.
TeamSCOPE needs to run a chat server process in order to allow the Java-based chat client to work. The chat server is named `scope-chat'. It supports the following options:
-d
--no-detach
Normally, scope-chat runs in the background, as a daemon. Use
this option to disable that behavior.
-l [log-file]
--log[=log-file]
By default, scope-chat logs chat activity to a file whose name is
specified in `scope.conf' at TeamSCOPE compile time. If
`scope.conf' is not modified before compilation, a suitable name is
guessed by the TeamSCOPE configuration script. To see the default log
file for your TeamSCOPE installation, use scope-chat --help.
Use this option to specify a different log file or disable logging. To use a different log file, specify its name. If no name is given, logging is disabled.
-p lo[-hi]
--port=lo[-hi]
By default, scope-chat listens on the lowest-numbered available
TCP port in the range 6555--6560. This option can be used to specify an
alternate port or port range. If only lo is specified, that is
the only port that will be used. If both lo and hi are
specified, the lowest-numbered available port in the specified range
will be used.
-P [pidfile]
--pidfile[=pidfile]
Enables the use of a "pidfile" and optionally sets the pidfile's
name. A pidfile is simply a file that scope-chat creates and to
which it writes its program id or PID, as shown by the UNIX ps
utility, among other tools.
The default directory for the pidfile is specified in `scope.conf'
at TeamSCOPE compile time. To see the default pidfile for your
TeamSCOPE installation, use scope-chat --help.
-h
--help
Displays a summary of scope-chat options and their meanings.
-v
--version
Displays the scope-chat version, copyright, and warranty
disclaimer.
You should set up scope-chat so that it is started when entering
a multiuser runlevel and stopped in other runlevels. A sample script
for `/etc/init.d' in a System V system is included in the TeamSCOPE
source tree as `debian/init'.
This document was generated on 13 September 2001 using the texi2html translator version 1.51a as modified by Ben Pfaff for TeamSCOPE.