7.1. Compilation/Installation Instructions

AUC has been tested on both Linux 2.2.x and IRIX 6.5. If you achieve success on additional platforms, please email the developers with any necessary changes to the source. Thanks!

Before installing, you must have MySQL C and Perl client libraries already installed on your system. Also, if your system uses PAM, AUC will automatically support it, assuming the proper client libraries are installed.

7.2. General Administrator Information

Note: This section of the documentation should be read after AUC has first been installed.

Any AUC installation should have at least one administrator. This person is responsible for creating/maintaining user accounts and making sure the classroom database is up to date. In addition, they should generally oversee the maintenance of the AUC server. At schools, this person could be anyone from a computer network administrator to a volunteer staff member. Some schools appoint a responsible student to be in charge of the AUC server.

7.2.1. After Your First Login

If you were successful in following the installation instructions, you should have logged in as a user with the same username and password as the user you created in the MySQL database. Assuming the login worked, you will see two "panes" in the resulting "Start Page." One of these panes allows the creation/maintenance of interactive classrooms and the other pane allows the creation/maintenance of user accounts. The first thing you should do is to create a user account for yourself. Make sure you give yourself "sysop" access priveledges when you create the account. If you make your username the same as your UNIX shell account's username, and you have PAM installed, you will then be able to log off and log back on with your username and password from your UNIX account. If this is not possible, read the section below about assigning passwords to user accounts.

7.2.2. Appointing Administrators

Depending on the size of your site, you may never more than one administrator to keep up with the needs of the server. If at any time you wish to "promote" an existing user to have administrative functions, simply change their access priveledges to "sysop" by editing the user info from the "Account Manager."

Remember that users with "sysop" access rights have the ability to modify any information on the server, including the contents of interactive classrooms, and any databases. Do not give "sysop" priveledges unless you trust that particular user.

7.3. User Account Maintenance

The most important part of any AUC installation is the users. After all, the whole point of AUC is for the users to create the content. Even if you are not experienced with administering a web site or server, administering AUC is a piece of cake. AUC uses a web-based interface for nearly all user management functions, allowing administration locally or remotely, and making changes quick and easy for even an inexperienced administrator.

7.3.1. Creating User Accounts

AUC users can be created from any account with "sysop" access (more on access priveledges later). You know you have sysop access when you can see the blue pane at the bottom of your start page labeled "Account Administration". Congratulations! You are an administrator now. To add a new account, first click the "Add Account Entry" link.

You will now see a page labeled "Add New User Entry". This is where you will specify the information on a new user. If you are unsure about any of the fields on this form, here is a description of each:

Username

A username is a unique handle that identifies a user from any other user. It is used fairly often when specifying a user, to prevent any ambiguity often resulting from using a full name. If you are maintaining a system with a large number of users, you should adopt a standard naming scheme for your users. For example, always using their first initial and first seven characters of their last name (In this case, David C. Moore would have the username "dmoore"). Also, if AUC is running on a multiuser unix system that allows telnet or email access to users, you should use the same username on AUC as that user has on your unix system.

First Name, Last Name, Middle Name/Initial

These items should be fairly self-explanatory. There's no need for these to be unique, but it's always a good idea to put in a full middle name if you have one. The user can always choose to have their middle name hidden or truncated on the system without you, the administrator, having to worry about it.

Student ID

Most schools have an established system for numbering or identifying students. If your school has such a system, put that piece of information here. However, it is not necessary for the database to operate, it is only for reference and for syncronizing your online with pre-existing school records.

Role

Use this field to specify the relationship of this person to the school. It will often determine whether or not they have access to specific features, and what panes they see when they login.

Class of

If this person is a student, what year will they graduate? An optional, but useful piece of information.

Access Level

For nearly all users, the correct answer here is "normal". However, if you want to restrict a user from any interactive features, select "guest", and if you want them to have administrative access (like you), select "sysop".

When you are done entering this information, click the "Add Entry" button to create your new user. They will be able to log in after you give them a password (see section 2).

7.3.2. Specifying a password

Assigning a password to a user on AUC is different than you might expect, but as you will see, turns out to be an extremely flexible and extendable method. Before giving passwords to your users, you must choose between two basic methods of authentication:

1. PAM-based Authentication - PAM (Pluggable Authentication Modules) is a shared library installed on many UNIX servers that allows authentication for many programs to occur in a centralized method. For example, the UNIX ftp and telnet daemons along with the login program will use PAM to authenticate users. This allows changes to be made to the authentication procedure without having to recompile all these programs. It also allows complicated auth. procedures. For example, a sysop could set up PAM to authenticate from a novell server just as easily as he could set it up to authentication from the /etc/passwd file. PAM needs to be installed when AUC is first installed for this method to work.
2. Database-based Authentication - This method stores users' passwords directory in the MySQL database. It is used when PAM is not available or when AUC needs to be set up in a quick and easy way. No external libraries are needed for this method.

You must choose between one of these two methods in order to allow users access to AUC. After you decide, your choosen method can be implemented as follows.

7.3.2.1. Implementing PAM-based Authentication

You should be comfortable with UNIX administration and familiar with PAM in order to implement this method successfully. Normally, the only necessary step to implement PAM-based authentication is to add AUC to your PAM configuration. To update your PAM configuration, add a file called "auc" to your PAM config directory (usually in /etc/pam.d/). A sample "auc" file is included in the conf/ directory of the AUC distribution. It can be adjusted as necessary for your site, but the default settings will work if you just want to use shadow passwords for AUC authentication.

7.3.2.2. Implementing Database-based Authentication

In order to give users a password for this method, you must add an entry to the password database by hand from the UNIX command line. Here is an example of how to do so:

DBUSER, DBHOSTNAME, and DBPASSWORD are your username, password and the hostname of the MySQL server. DBNAME is the name of the database you created for AUC. USERNAME and PASSWORD are the username and password of the user you are adding to the system.

Note: in future version of AUC, this method will have a web-based tool for maintaining passwords

7.3.3. Managing Existing Users

To modify information about any users on the system, select the "User Account Manager" link from your Start Page. The User Account Manager displays a list of all the users on the system, sorted and paginated by several possible fields. You can select a different sort field from the drop down box at the top of the screen. Different pages can be chosen from the list the appears just above the table of users. The "options" column has a variety of links to modify the selected user:

7.3.3.1. Edit Function

By selecting the "edit" link, you can change any information about a user that you specified when creating that user. See the section on "Creating User Accounts", above, for a description of the fields.

7.3.3.2. Delete Function

The "delete" link will delete a user completely from the system. You will be asked for confirmation before the operation is performed. Note that a user deleted here will NOT be recoverable. However, any files that the user uploaded anywhere (including their home directory) will be preserved. Also, any comments posted in discussion forums will remain.

7.3.3.3. DirInfo Function

The "DirInfo" link allows the administrator to add information to a user's account that will appear in the Directory Listing for that user. The fields are as follows:

Street Address, City, State, Zip Code, Phone Number

Contact information for the user. Note that only a system administrator can modify this information, not the user. Also, users in the "student" role will be unable to see this information for users in the "staff" role. Thus, it is safe to include contact information for teachers, as long as they are willing for other teachers to see this information. Students will only be able to view contact information for other students.

E-Mail Address, Homepage

More information for a user. This info can be modified by the user from his/her own directory entry. Therefore, it is often not necessary for a system administrator to make any changes.

Greeting Text

The greeting text also appears in a user's directory entry. It can be left alone, as a user can modify this for themselves.

Click "Save Entry" to update the information.

7.3.4. Group Management

Groups are necessary when the administrator wishes to designate a certain user or a certain set of users to have access to a private area of AUC. For example, any user in the "newspaper" group will have access to the staff only area of the newspaper, allowing them to have full control over the text and publication of the online school newspaper.

7.3.4.1. Adding a Group

To add a group, click the "Add Group" link in the "Account Administration" portion of an administrator's Start Page. The resulting form is used to specify the name of the group as well as any members of the group. For the name, it should be all lowercase and 8 characters or less with no spaces. Specify the usernames of any users that should be in the group (they can be adjusted later), one per line.

7.3.4.2. Modifying Groups

To access a list of groups, click the "Group Manager" link from the Start Page. A list of groups will appear will various options. The following changes can be made:

Delete a user from a group

Click the "(d)" link beside the user's name

Add users to a group

Click the "Add User(s)" link next to the group and use the resulting form. Remember to specify one username per line.

Delete a group

Click the "Delete Group" link next to the group. You will be asked for comfirmation before the group is removed.

7.3.5. Additional Notes about User Accounts

7.3.5.1. Home Directories

The Home Directory is the link that appears in the "File Servers" section of the Start Page. If the PAM-authentication method is being used (see Section "Specifying a Password") and the user already has an account on the userlying UNIX server, "Home Directory" will access the files in the users tradional UNIX home directory. Otherwise, a temporary directory will be created for the user's "Home Directory."

7.3.5.2. Email Access

If PAM-authentication is being used, and the user has an account on the underlying UNIX server, the "E-Mail" component of AUC will be able to access the local mail spool for that user. In addition, AUC uses the same mail preferences file as pine (the ~/.pinerc file), allowing pine and AUC to coexist peacefully. If the user has no account on the server or PAM-authentication is not being used, the user will still be able to set up IMAP access for the "E-Mail" component of AUC.

7.4. iClassroom Maintenance

There are three main components to think about relating to the Interactive Classrooms. These parts are:

1. The Master Calendar
2. The Database of Classes
3. Individual Classroom Content

7.4.1. Setting up the Master Calendar

The Master Calendar needs to be configured properly for many functions of the interactive classrooms to work. It normally only needs to be updated once per year.

To set it up, click the "Master Calendar" link in the "Classes Administration" pane of your Start Page. You will be presented with a configurable list of dates. Note: AUC is hardwired at the moment to work only with "block scheduling," a style of scheduling where the 7 or 8 periods of a student's class schedule are split between two days, with approximately 90 minute periods each day. However, in the next version, block scheduling will be an option, and not required. AUC also assumes that your school has two semesters per year. This will also be configurable in the future.

"Semester 1 First School Day", "Semester 2 First School Day", "Semester 1 Last Regular Day", and "Semester 2 Last Regular Day" should be self-explanatory. Just set them to the proper days. The other two dates, "Semester 1 First Odd Day" and "Semester 2 First Odd Day" are the dates that block scheduling starts for each semester. If your school has a day or two of normal scheduling before block scheduling begins, the "odd" day should be the first day of block scheduling. If no such grace period exists, just set the first "odd" day to the same day as the first school day.

Click "Save" when all the dates are correct. These options should be set once per school year.

7.4.2. Adding Interactive Classrooms

Before adding classrooms, you should do some careful planning. You probably have a lot of classes being taught at your school. It would be a good idea to get a master list of all the classes along with teachers and other necessary information. This ensures that you are consistant with the information you add to the database. If you have an electronic copy of the schedule, you could add all the classes to the database by altering the SQL database directly. However, doing so is beyond the scope of this document.

To add a class to the database of classes, select the "Add Class" link from the "Classes Administration" pane on your Start Page. The resulting form will allow you to specify details about the class you are adding. The necessary fields are as follows:

ID Number

An ID Number is a unique number assigned to each classroom. It should be 8 digits long to work correctly in AUC. The first 6 digits of the number should be unique to the class's subject. The last 2 digits should be used to seperate one class from another when there are multiple class periods and/or teachers for the same subject. When classrooms are accessed online, each teacher-subject combination is giving a seperate classroom. You should still add each class individually if a teacher teaches the same subject in multiple periods, but the documents and discussion forums for these periods will be identical. It is important to realize that this database of classes is not a one-to-one correspondance with the resulting interactive classrooms. This may seem confusing at first, but read over it again, and you will realize the usefulness of this behavior.

Title

The name of the class.

Teacher's Username

The 8-character field corresponding to a teacher in the AUC user database. The user does not have to exist yet in order to be specified here. However, the user should be created before students are expected to use the classroom online.

Room

The room number where the class is taught.

Department

The field determines in which department of the school the class is. It determines sorting in the class manager, and also determines the graphic used in the interactive classroom online. Note: In future version of AUC, you will be able to modify the list of possible departments.

Period

Which period of the day the class is taught.

Semester

Which semester the class is taught. If the class is taught in both semesters, include a seperate database entry for each.

Additional ID Numbers

Any additional 8-digit codes can be specified here. They will simply be aliased to the class's initial code. This is useful if you need to have multiple subject codes correspond to the same class. Any 8-digit codes specified here should not appear elsewhere in the database.

When you are done entering this information, click the "Add Entry" button to create your new class. The class will then be accessable from AUC, and can also be added to anyone's interactive schedule, by using the "Customize Schedule..." link, and specifying the 8-digit code.

7.4.3. Managing Existing Classrooms

The class database can easily become very large if a school has a lot of classes taught during the year. AUC has been tested with over a thousand classrooms, and still operates just as fast as with a only handful of classes. The Class Manager is used to maintain these classes. It can be reached from the "Class Manager" link in the "Classes Administration" pane of the Start Page.

7.4.3.1. The Class Manager

The Class Manager operates in much the same fashion as the User Account Manager. It lists all the classes in the database, and can be sorted and paginated by several fields. There are two main functions available from the class manager for each class:

Edit Function

Allows you to modify the various parameters for a class. For a description of these parameters, see the above section on "Adding Interactive Classrooms." Note: Changing the ID Number for a class should be avoided if the class has been in use for some time. If this number is changed, any data (documents, discussions, etc.) in the classroom will no longer be available. (However, the data is not lost. See the section below on "Advanced Classroom Maintenance" for the specifics on where documents are stored on the server.)

Delete Function

Deletes the selected classroom from the database. This includes any discussion forums, scheduling information, announcements, and log entries. Any handouts, documents, or any other files uploaded to the file area of the classroom are NOT deleted. To recover these files, see the section below on "Advanced Classroom Maintenance."

7.4.3.2. Advanced Classroom Maintenance

Depending on your number system for classes, a certain teacher's class may change ID numbers from year to year. If a class's subject-teacher identifier (remember that a unique subject is determined by the first 6 digits of the class ID) ever changes, all the documents will appear to be lost for that class. Even though the teacher may no longer be able to see these documents, they are still available on the server.

In most installations of AUC, all the classes' data files will be stored in the directory /var/auc/class. Each class will have a subdirectory within that directory named according to the subject-teacher identifier. If a class is deleted, renamed, or moved, the directory of files will still exist. It is up to the system administrator to remove these files by hand. Also, the contents of the directory can be moved to another class, or put in a teacher's home directory.

7.5. FAQ for Advanced Administrators

Here is a list of frequently asked questions about more advanced administration topics not completely covered in the documentation above.

7.5.1. Why is the auc.cgi binary suid and sgid?

When a user logs in to the system, AUC may have to authenticate a user using PAM. PAM requires a client application to have superuser priveledges in order to authenticate. However, as soon as AUC has authenticated (or not) a user, it will drop it's superuser priveledges in favor of the user's uid and gid (if the user has a local account) or the same uid and gid of the web server (in all other cases).

7.5.2. How can I change which panes appear on a user's start page?

Edit the files in /etc/auc that have names home.GROUPNAME, where GROUPNAME is the name of a group to which a user would belong. These files contain a newline-seperated list of panes to appear in a user's start page if the user is a member of that group. To see a complete list of possible pane names, look in the src/nodelett.h file in the source code of the AUC package.

7.5.3. Where does a user's home directory actually exist on the filesystem?

If the user has a local account on the server, their normal home directory will be used for the "File Servers" pane of their Start Page. If they do not have a local account, a home directory will be created for them in /var/auc/home. It is important to note that if you create a local account for a user who has had an AUC account for some time, you should move any of their files in /var/auc/home/USERNAME to their new home directory.

7.5.4. Can I set up AUC to authenticate users using some external database? (an NT Domain, Novell, etc.)

Yes, any authentication scheme is possible using PAM. If you have PAM currently configured to authenticate to an external database for another service such as 'login', you can just copy /etc/pam.d/login to /etc/pam.d/auc. This modification will work in nearly all cases. Numerous PAM modules are available on the 'net to authenticate to various types of external databases, however the exact configuration of such a setup is beyond the scope of this document. See the PAM documentation for more information.