Caucus ª  2.7

Installation and System

Manager's Guide

for UNIX

by: Screen Porch LLC

http://screenporch.com

COPYRIGHT
Copyright © 1988-1996 Screen Porch LLC.  All rights reserved.

The Caucus computer program is copyrighted and all rights are reserved by Screen Porch LLC.  As the original purchaser of the Caucus computer program, you are entitled to maintain the program, as is, on your computer system.  Copying, duplicating, selling, or otherwise distributing the Caucus computer program, except for the limited purpose of system backup, is a violation of the law.

The Caucus Installation and System Manager's Guide for Unix is copyrighted and all rights are reserved by Screen Porch LLC.  This guide may not be copied in whole or in part without the express written permission of Screen Porch LLC.  The term "copied" extends to all forms of duplication including, but not limited to, photocopying, ink duplication, reduction to electronic media or machine readable form, or translation to any other language.

DISCLAIMER

Screen Porch LLC makes no representation or warranty concerning the content of this document and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose.  Screen Porch LLC further reserves the right to revise this document or the product it describes without obligation to notify any person or organization of such revision or change.

TRADEMARKS

Caucusª is a trademark of Screen Porch LLC.  Unix is a trademark of AT&T.  Screen Porch LLC is a division of Screen Porch LLC, Inc.

Revised April 1994.  This document was produced with Microsoft Word 5.0 and printed on an Apple Laserwriter II.

Table of Contents

Chapter 1	Introduction

1.1 	How to Use This Manual	
1.2 	Purpose	
1.3 	Background	
1.4 	Security	

Chapter 2	Installation
Editor’s Note	3

Chapter 3	Using Caucus

3.1 	How to Join a Conference	

Chapter 4	Captive Caucus

4.1 	System Versus Captive Userids	
4.2 	Setup	
4.3 	Implications	

Chapter 5	Managing Caucus

5.1 	Caucus Management Overview	
5.2 	Creating New Conferences	
5.3 	Deleting Old Conferences	
5.4 	Adding Users	
5.5 	Deleting Users	
5.6 	Creating Custom Caucus Commands	
5.7 	Managing Captive Caucus Use	

Appendix A

Cv2check	17

Appendix B

Problems and Solutions	19

Chapter 1

Introduction

1.1	How to Use This Manual

This manual contains complete instructions for installing and managing the Caucus 2.7 (text interface) electronic conferencing system on your Unix computer.  For information about the World-Wide-Web version of Caucus, see the Caucus 3.1 Installation Guide.  To learn how to use Caucus 2.7 once it is installed, see the accompanying Caucus 2.7 User's Guide.

This manual is divided into six major sections:

•	Chapter 1: Introduction
	General information about Caucus and this manual.
	
•	Chapter 2: Installation
	How to install Caucus on your Unix computer.
	
•	Chapter 3: Using Caucus
	How to begin using Caucus once it is installed.
	
•	Chapter 4: Captive Caucus
	Optional use of a single userid to provide access to Caucus for many people.
	
•	Chapter 5: Managing Caucus
	How to create new conferences, delete old ones and, in general, manage Caucus on your computer.
	
•	Appendices
	How to adapt Caucus to your specific needs.  This includes additional utility programs, Caucus command line options, and how to define new Caucus commands.

1.2	Purpose

Caucus is a software program that provides for computer conferencing, also known as computer-mediated or electronic conferencing, on a wide variety of computers ranging from micros to mainframes.  This version of Caucus provides conferencing on computers running the Unix or Xenix operating system.

1.3	Background

This document assumes that you are familiar with normal system management functions associated with running Unix.

1.4	Security

A Caucus conference is as secure as the Unix operating system will allow.  That is, when Caucus is properly installed, only the root and Caucus userids can directly access the files that make up a conference.  Only the system manager should know the password to these userids.

The only way that other users can access a conference is by using the Caucus program, which is installed with the "Set Userid" protection bit.  The Caucus program rigidly controls who can enter or change text in a conference.

Individual Caucus conferences may be open to everyone or limited to certain people.  For more information, see Chapter 12 of the Caucus 2.7 User's Guide.

Chapter 2

Installation

This chapter has been replaced by the Caucus 3.0 install guide.  Please see that document.

Chapter 3

Using Caucus

3.1	How to Join a Conference

To use Caucus, login to your personal userid and type:

	cv2

You will see the prompt:

	JOIN which conference?

Type the name of the conference you want to join, or:

	STOP	to get out of Caucus
	HELP	for assistance
	LIST	to see the list of available conferences
	CHECK	to see a summary of new material in your conferences

The Caucus software comes complete with a sample conference named DEMONSTRATION.  You can join this conference immediately and see how different organizations have made use of computer conferencing.  See the Caucus Menu User's Guide and the Caucus User's Guide for further information about using Caucus.

Chapter 4

Captive Caucus

4.1	System Versus Captive Userids

There are two ways that people can use Caucus.  The most common method is described in Chapter 3: each user logs in with his or her personal userid and types

cv2

The other method is called captive Caucus, because it requires one userid that can only use (i.e., is captive to) Caucus.  If you have a group of people that wish to use Caucus (and do nothing else), you can set up one userid that will serve them all.

This chapter describes how to set up a captive Caucus.  If you are not interested in this feature, skip to the next chapter.

4.2	Setup

To set up a captive Caucus, the system manager must create a new userid that will run Caucus and nothing else.  For the sake of example, call this userid "Cap".

Start by creating the Cap userid as you would for a normal user.  Next, change Cap's login shell to be the file cv2cap in the Caucus userid.

For many Unix systems, this can be accomplished by logging in as root, and editing the /etc/passwd file.  Examine the line for the Cap userid.  The last field on this line is the name of the login shell for that userid.  It is typically /bin/sh.  Change it to the full pathname of the file cv2cap in the Caucus userid.

Warning!  If you are not familiar with Unix user administration, or the format of /etc/passwd, read the relevant Unix documentation first!  Make a backup copy before you actually edit the file.

4.3	Implications

When a user logs into Cap, Caucus starts up automatically.  It immediately prompts the user for a name and a password.  Since Caucus keeps track of these names and passwords, the one Cap userid can handle many different users at the same time.

Once the user has supplied a correct name and password, he or she is prompted to "JOIN which conference?" as described in Chapter 3.  Leaving Caucus with any of the STOP, QUIT, etc. commands logs the user out.

The cv2cap file tells Caucus to allow anyone to register a name and password for a new user.  If you prefer, you can restrict Caucus to allow only the Caucus manager to register new users.  To do this, login to the Caucus userid.  Edit the file captive.opt and add the NEWUSER OFF option.  (For more information on  Caucus options, see Appendix B.  For more information on the capabilities of the Caucus manager, see Chapter 5.)

Chapter 5

Managing Caucus

5.1	Caucus Management Overview

Once Caucus is installed, it also needs to be managed.  One person should be designated as the Caucus manager to handle the infrequent duties listed below.  This person need not be a system manager, but does need to know the password to the Caucus userid.

The Caucus manager's duties include:

•	creating new conferences
	
•	deleting old conferences
	
•	deleting users
	
•	creating custom Caucus commands
	
•	managing captive Caucus use

5.2	Creating New Conferences

While the DEMONSTRATION conference is a good way to see what Caucus is all about, it is recommended that you create a new, empty conference for all of the users on your system.  If you later find that you need multiple conferences to serve distinct groups of people, you can create them as you need them.

To start a new conference, login to the Caucus userid and type:

	cv2start

You will be prompted for the name of the conference, the type of the conference (regular discussion conference or file library), and the userid of the organizer of the conference.  The Cv2start program then will proceed to create the new conference.

The organizer of the newly created conference should join the new conference as soon as is convenient.  See the chapter "Organizing a Conference" in the Caucus User's Guide.

5.3	Deleting Old Conferences

The time may come when you want to remove a conference from your computer.  This can happen for several different reasons:

•	Some conferences may be set up for a specific purpose or to plan for a specific event.  Once the event is over, there may no longer be a need for that particular conference.
	
•	A very active conference can get so big (several thousand items) that keeping track of everything becomes very difficult for its participants.  In that case, the organizer may re-start the conference: that is, start a completely new, empty conference, copy over the most important items, and go on with a fresh slate.  Once all the participants have switched over to the new conference, the old one can be removed.

If you re-start a conference, it is a good idea to save the contents of the conference on some backup medium before removing the old conference.  The Caucus command:

	show all items >file

will put the text of the entire conference into file, which may be archived to magnetic tape or diskettes.

To delete a conference from the system, login to the Caucus userid and type:

	cv2remov

You will see a list of all of the conferences and be prompted for which one you want to delete.  Caucus will ask you for confirmation before it deletes the conference you selected.  To exit cv2remov, press <RETURN> when asked "Which Conference (<RETURN> to quit)?"

5.4	Adding Users
Caucus managers may pre-register a list of users automatically.  This may be helpful when opening Caucus to a new department, or students in each new school year.  To pre-register users, use the command, register.

To use register, you must specify a filename on the command line.  For example, to register users from the file prereg, type "register prereg".  The file, "prereg" must be in the home directory of the Caucus account and contain the pre-registration information described below.

5.4.1	File format

The file which contains the list of users must be in a specific format.  This format includes some necessary information and some optional information.  The following information must be included:

•	Full Name
•	Last Name
•	User ID (either computer account ID or captive Caucus ID)
•	Telephone number
•	Password (if captive)

The following information may also be specified:

•	Default settings
•	Personal Introduction
•	User Variables
•	Initial conferences
•	Comments

The file may include information for as many users as the system will support (hundreds of 1000's).

The information for each person must be supplied on 2 or more lines.  These lines must be together in the file.  The first of these supplies the 4 or 5 bulleted items in the mandatory list above, e.g.:

	Jeff Victor:victor:jvictor:(518)-273-0983:

Note these rules about the first line of a person:

•	Each field must be terminated by a single colon.
	
•	No field can have a colon in it.  This is especially important for the User Name, Telephone Number, and Password fields.  The other fields shouldn't have a colon in them anyway.
	
•	The only thing that distinguishes the fields is their order on the line!
	
•	The first and fourth fields are free-text fields, and can contain Roman characters, kana, and/or Kanji.  For example, the phone number can be anything.  The second field must be one word, but can contain Romanji, kana, and/or Kanji.  The third and fifth fields must be one word each, lowercase ASCII, with no spaces.
	
•	The phone number can be blank, but the (empty) field must still be terminated by a colon.
	
•	The presence of a fifth field (not included in the above example) indicates that this user should be a captive user.  The software will add a trailing underscore ('_') character to the person's ID.

The fifth field is the user's password.  The password can be blank, but you must use a trailing colon to indicate that there is an empty password there, and that therefore this should be a captive user.

So, the official technical specification for this line is:

	Full Name:last_name:userid:phone:[[password]:]

where the '[' and ']' indicate an optional field.

The rest of the information lines for a person each begin (in the first column) with a special letter indicating the type of information supplied by that line.  This letter must be uppercase.

The other mandatory line is just a line indicating that this is the end of this user's description.  It is a single 'E' in the first column.

Here is an example of the simplest description:

	Jeff Victor:victor:jvictor:(518)-273-0983:
	E

5.4.2	Optional Information

In the order described above:

1)	The Settings line must begin with an 'S'.  This line must be in the same format as the "sys_Tset0" string in the dictionary file "america0".  Any legal values can be specified.  If the manager chooses to have the user start off with the 'normal' default settings, the line looks like this:

Soff 23 79 off caucus 8 12 default on 0 . off wordwrap 0 later execmenu

2)	A Personal Introduction can be many lines long.  Each line must begin with an uppercase 'I'.  Each line may contain Romanji, kana, and/or Kanji.

3)	User Variables are one line each.  Each line must begin with an uppercase 'U'.  This must be followed immediately by a digit from zero to nine.  The rest of the line can be followed by free-text.  Each line may contain Romanji, kana, and/or Kanji.

4)	Initial conferences are one line each.  Each line must begin with an uppercase 'C'.  This must be followed by the entire conference name.  CaucusLink systems must specify the "True Conference Name" as described in the CaucusLink Manager's Guide (section 2.4).  Although initial substrings of conference names can often be used, if an ambiguous name is used, the user will not be joined to the conference, the program will complain to the manager, and then it will continue.

5)	You can insert comment lines anywhere in the file.  To signify that a line is a comment and should be ignored by the maintenance programs, start it with a '#' ("pound sign", or "hash mark").  Each line may contain Romanji, kana, and/or Kanji.

5.4.3	Examples

A complete example:

#This is the first user:
Jeff Victor:victor:jvictor:(518) 273-0983:
Soff 23 79 off caucus 8 12 default on 0 . off wordwrap 0 later execmenu
IThis is a user's brief introduction.
IIt is two lines long.
U1This is the value of the User's Variable $(U1)
U8This is the value of the User's Variable $(U8)
# This is a comment
# The rest of the lines for this person are conferences to join the user into:
Cdemonstration
Csales
E
#
#This is the second user.  This is a captive user.
Charles Roth:roth:roth:(518) 273-0983:camber:
#We'll accept the default settings.
IThis is the introduction.
Cdemonstration
E

5.4.4	Errors

•	If the program detects an unrecoverable error about a particular user (e.g. that ID already exists), it will complain about the user, not register him/her, and attempt to continue.
	
•	If the program thinks that the disk is full, it will mention this and then give up.
	
•	The software tries to protect the use from most mistakes, but it's possible to really confuse it, in which case it may complain and give up.  On the other hand, if you include a colon as part of a user's name, it may fail in strange ways.

5.5	Deleting Users

On occasion you may also wish to delete a user.  For example, if you are managing Caucus at a university, you might delete users who have graduated and left town.  Deleting a user removes the user from all of the conferences and frees the disk space taken up by the user's message and participation files.  It does not remove any of the user's items or responses.

To delete a user, login to the Caucus userid and type:

	cv2kill

You will be prompted for the name of the user to be deleted.  Caucus will ask for confirmation before it deletes the user.  To exit cv2kill, press <RETURN> when asked "Which User (<RETURN> to quit)?"

5.6	Creating Custom Caucus Commands

Caucus provides a great deal of flexibility with its menu and macro features.  The Caucus manager can create new commands (called macros) that Caucus will recognize at the "AND NOW?" prompt.  These macros may be defined as any combination of Caucus and Unix commands.

For more information about Caucus menus and macros, see the separate manual Customizing the Caucus User Interface.

5.7	Managing Captive Caucus Use

If a captive Caucus userid has been set up (see Chapter 4), the Caucus manager may also be responsible for managing the list of captive Caucus users.  This consists of two activities:

•	registering new users:
	To register a new captive Caucus user with a name and password, login to the Caucus userid and type:
	
	cv2pass
	newuser
	
	and supply the new user's name and password when prompted.
	
•	resetting passwords:
If a captive Caucus user forgets his or her password, you can change the password to something new.  Login to the Caucus userid and type:

	cv2pass
	password

and enter the user's name and new password when prompted.

Appendix A

Cv2check

Cv2check is a separate utility program that is supplied with Caucus.  It provides a quick way for users to determine which conferences have new activity.

For example, if you are a member of six different conferences, you might join each of the conferences in order to see if there was something new on any of them.  With Cv2check, you do not need to join any of them.  At the Unix prompt ($ or %), type:

	cv2check

You can also type this command at the "AND NOW?" prompt.

Cv2check will tell you which of your conferences have new items or responses and whether you have any new messages.

Appendix B

Problems and Solutions

Here are some typical problems that people have had with Caucus, along with the solutions:

	1.	The installation procedure ran just fine, but when I type CV2 or CAUCUS nothing happens.

At the end of the installation procedure, the system manager should have copied the files cv2 and cv2check into a public directory.  This directory must be included in each individual user's search path.

	2.	The second time I used Caucus it asked me to register again.  

You probably joined Caucus from two different userids.  You should stick to one userid when you use Caucus.  If you really want to use Caucus from the second userid, have the Caucus manager delete you as a user and start over.

	3.	When I run Caucus it complains about "ss_dotnl" and says it cannot access its dictionary.

Possibility 1: the Caucus program has the wrong permission bits set.  Login to the Caucus id and type "chmod 4711 BIN2/caucus_x".  If you are running a C2 secure system, the system manager may have to type this command as "root".

Possibility 2: the wrong dictionary was compiled.  Login to the Caucus id and type "cv2mkmd diction0 0".

Possibility 3: when Caucus was installed, the cinstall script was not run.  If the Caucus directory contains a directory called NEW_C001, this is probably the case.  Login to the Caucus id and run cinstall.

Possibility 4: some users were still running an old version of Caucus when the new software was installed.  Verify that no one is using Caucus, and re-do the entire installation procedure.