This document is provided both on our web page, and in your download. It describes and discusses installing Shared Calendars on your system. See Step By Step Configuration Guide to get started quickly.

Shared Calendars 2.0 is very easy to learn and use. Unfortunately, the one difficult step is the first one: configuring it for your system. If you are having any difficulties, please do not hesitate to ask us for help.

Early Release notes: while the bulk of the code base is similar to version 1 which is well tested and quite stable, we have completely reworked and only lightly tested the configuration.  We expect problems, so please don't give up or get stressed if you run into problems, just email us.

NOTE: Shared Calendars requires PERL version 5. If your system runs an earlier version, you will need to talk to your ISP to update PERL to version 5.
 

GETTING STARTED

• Step By Step Configuration Guide
• Notes on Configuration Options
1. Security Basics
2. Automatic Notification by Email
3. Creating A Public Calendar
• Server and Security Issues
• If something doesn't work...

 
 

• Changing The Look [Ex.: Logos, 24 hour time]
• Making Changes to the Initial Configuration
• To remove unwanted users
• Moving Web Pages
• Making Changes to the Program

• Contact, Ordering and Registration

Step By Step Configuration Guide

* These instructions are intended for users of just the 'Core' license. If you intend to purchase the 'Business' license, contact us at any time in this process and we will directly assist with configuration.
* It is preferred but not necessary to install Shared Calendars while logged in under the same user account as your Web Server (for example, as www). We recommend against using the root account.

1. Download CalendarV2.tar.gz, via HTTP (web browser) or via anonymous FTP from ftp.boutell.com in the subdirectory: pub/boutell/calendars
2. Move it to the program directory. This should be a directory not accessible via the Web, where program files will be kept and data stored in a subdirectory called "Calendar/", which will be created in the next step...
3. Unzip it by typing: "gunzip CalendarV2.tar.gz".
4. Type "tar -xvf CalendarV2.tar" to un-tar it, creating the "CalendarV2/" program directory. Ideally, do this under the same userid as your web server, typically "www" or "nobody", allowing you to set more restrictive permissions
5. Change directories to the newly created directory "CalendarV2".  Make sure this directory is read, write and executable by your web server. (chmod 744 CalendarV2/ if your Calendar directory is the same userid as your web server, chmod 777 otherwise.)
6. Copy 'makeconf.cgi' to your web directory, where it can be executed as a Perl 5 program.  You may need to edit the first line to point at your Perl 5 directory (The first line is set by default to "#!/usr/bin/perl".  Leave the characters "#!", followed by the path to your perl directory.  If you are not sure, you can try our default, then edit it only if it doesn't work.)  You might want to put makeconf.cgi in a protected directory where only you can access it; otherwise, we recommend you remove it or change the permissions so it is unreadable when you are taking a break or finished (so that noone else can come along and install another copy on your system). Also, you can copy or use AdminInstructions.html from there, instead of using this version on www.boutell.com, if you prefer.
7. Use your web browser to view 'makeconf.cgi', our configuration program. This will ask a series of questions, and then allow you to configure Shared Calendars based on your answers.  From here on,  makeconf.cgi will wall you through the steps.   If you are about to configure Shared Calendars, you can begin using makeconf.cgi and only come back to this AdminInstructions file if you have questions not answered there.  Otherwise, browse this file to know what to expect when running makeconf.cgi. See below for discussion of the nuts and bolts of configuration.

 

 
 
 
 
 

8. [makeconf.cgi  will instruct you to] configure Shared Calendars step by step.  If you are not using the default setup or run into difficulties on your system, you'll do some of the steps by hand; otherwise makeconf.cgi does it for you.
9. [makeconf.cgi  will instruct you to] have your system run our mail program every 20 minutes using crontab (or however you wish.)
10. [makeconf.cgi  will instruct you to] create an administrator account, from which you can create more accounts.
11. (If you haven't already, this would be a good time to read the short Help pages.)
12. [makeconf.cgi  will instruct you to] create a calendar called "Holidays", if you wish. You will create this calendar the same way you create any new, empty calendar (by pressing the button "Create New Calendar"). However, data for some Holidays will already exist. You need to create Holidays since we cannot arbitrarily decide who has access to it. Feel free to edit it just as you would a Calendar that you created from scratch: adding, removing or editing holidays.
13. [makeconf.cgi  will instruct you to] edit the files BodyTag and Footer, in your working directory, if you wish. BodyTag contains the < BODY > command, and both files can contain extra HTML. These are here for you to add your logo, images or whatever notes you want. The BodyTag file will be read and printed before the rest of the Calendar is printed, and the Footer will be printed at the very bottom of the web page. The BodyTag usually contains a note about the Time Zone (remove or edit the message if you want).

Notes On Configuration Options

Our makeconf.cgi program will walk you through what we consider the most likely and most generic scenarios. If you are using the Apache server and setting up a new security system or have password files that can easily be read by this program (beta users: expect to contact us if you have your own password files), you can probably configure your system quickly using makeconf. In case you want to do something different, we explain below what makeconf does, so that you can alter it or do it yourself. We've tried to write PERL code that can be edited reasonably easily.

NOTE: You must use PERL 5. If your system is configured to use an earlier version when you type "perl ./makeconf", it will not work. Please upgrade to PERL 5. 

Security Basics

Following is a discussion of what the makeconf program will do for you under a variety of desired security set-ups. "makeconf" will walk you through the specifics for simpler setups, so don't worry about the details here. This section should help you understand the broad approach, or if you are an expert who wants to change the way we do things, you can get started with this information.

Quick Overview

If you use our default security system, Shared Calendars (both makeconf.cgi, and the program itself when you are logged in as an Administrator) can create new accounts.  You also have the option of creating an application program, so that users can create accounts over the web (this can be placed in an unsecured directory, or in a directory which you have protected by some other means.)

Building a Secure Directory Using makeconf

Whether or not you use automatic over-the-web account generation, a directory accessible via the web will be secured, by placing the file ".htaccess" in it. This is where the calendar program itself will be kept (file name "index.cgi").

If you use automatic over-the-web account generation as well, where people can automatically set up an account and get a password without your oversight, then makeconf will set up a new, un-secured directory, with the file "apply.cgi" in it. When you announce the Calendar program, send potential users to this web address, and they can input their names and email to get passwords.

Another way to create new accounts is to log into the calendar as "Admin". Under "Personal Options" will be the option to create new accounts. This is the simplest way to create new accounts if you are not using automatic account generation - BUT, you must first create the Admin account by hand.

If you don't want automatic password creation, Shared Calendars will do it for you, if you are logged in as Admin. First, you'll need to create an Admin account, which makeconf will guide you through. [ makeconf will use "htpasswd", placing the password file at "YourWorkingDirectory/DATA/Office/calendar.pwd" ].

Unless Usernames are also email addresses, you'll need to add the email address. Load up the Calendar, and go to Personal Options [a button near the bottom]. Set an email address for the Admin account you just created.

Once the "Admin" account is created, you can use "Personal Options" in Shared Calendars, while logged in as Admin, to create new accounts. This method has the advantage of automatically sending email to the new users.
[ Or, if you prefer, you can enter new users by typing "htpasswd YourWorkingDirectory/DATA/Office/calendar.pwd UserName", and if necessary entering the email addresses another way. ]

Integrating with an Existing Security System

Some functions in Shared Calendars require the names of all the users. So, makeconf needs to be told where a file with all those names can be found. Typically, the names of all users can be found in a password or email file, somewhere on your system. However, it is likely [we assume] that the names will be followed by a password or email, in a format like:
name1:email1
name2:email2
name3:email3

Shared Calendars can read formats like this. In this example, when asked by makeconf for "File containing user names:", enter the name of the above file. When asked for the "Character separating data in above file:", enter the colon, ":", that is used to split the name from the rest of the data. If the file contains nothing but the names, then just enter a "return". [Note that the above file does not have to be a password file; it could be a list of just names, or other information like email addresses instead of passwords.]

If UserNames will not act as their email addresses, then be sure to use the email file, in a format like that above [makeconf will walk you through this].

CONTACT US.  The following information is out of date:  If your security setup does not follow this style, you'll need to edit our Perl code to read the names. Edit "sub GetPeople" in "Subroutines.pl" to get the list of users, and "sub GetEmail" in "Password_Related.pl" to get the email addresses [if you need them], or contact us. 

Automatic Notification by Email

To do so, you need to run the program "MailCal.perl" every 20 minutes. "makeconf" will ask if you want it to launch your 'crontab' file, which on most systems is the best way to have a program run at repeating intervals. If you say "yes", than makeconf will tell you the line you should cut-and-paste into the crontab file, and will run "crontab -e" for you.

Specifically, you will be adding the line:
0,20,40 * * * * YourWorkingDirectory/MailCal.perl which will run MailCal.perl on the hour, and at 20 and 40 minutes after the hour.

 If you'd rather do it yourself or use a different way to automatically run "MailCal.perl", go right ahead. If for some reason you can not run MailCal.perl regularly, mail notification will not work, but the rest of the Calendar will work fine.

Creating A Public Calendar

The "Public" Calendar Site is a normal web site for the public to view: people without accounts will be able to see (but not change) a Calendar Site with a subset of the entries that people with secure accounts can see.

The configuration program "makeconf" will quickly guide you through the creation of a "Public" Calendar Site, if you want one. The "Public" Calendar Site is accessed using a separate "cgi" program, but uses the same data as your secure Calendars Site. Changes to the "Public" Calendar are made at the secure site, by whoever has access to change your publicly accessible calendars (named "Public" by default).

How to:
As a user (under the account Admin or any other account you would like to control the Public calendar from), create the Calendar called "Public" [be sure to spell and capitalize it just like this]. All events entered on this "Public" calendar will then be visible at the URL you entered while configuring.

Other Information Needed

To Invoke Perl Interpreter:

If you're not sure, try looking at the first line in the code of any other Perl program.
 

Using Usernames as Email Addresses

Server and Security Issues

Know how you are allowed to run cgi programs:

What User ID will run the perl cgi programs?

Where to put cgi programs?

• placed anywhere other web documents are, but with a .cgi suffix. [To implement this for Apache, un-comment this line in srm.conf: "#AddHandler cgi-script .cgi"]
• in a cgi-bin: make sure you put our cgi programs there ( the main index.cgi, and if you use them the application program and Public calendar.) For Apache servers, the location of this bin is set in the configuration file "access.conf".

Basics: Make sure cgi programs can run at all

Options ExecCGI

What Server Settings Block Shared Calendars?

Problems that may occur when we try to create security for you:

 AuthUserFile /home/.../calendar.pwd
AuthName Calendar Access Control
AuthType Basic
require valid-user

Some Server Configurations can block this from functioning: [The following information is for Apache servers.]

 AllowOverride
In access.conf, the setting "AllowOverride" may be set in a way that does not allow .htaccess to work. For example, "AllowOverride None" will prevent the security system we set up from working. (Be sure to set AllowOverride correctly in the appropriate directory - if you fix it globally but it is set back to "None" in your cgi-bin, it won't work.)

AccessFileName
In srm.conf, "AccessFileName" should be set to ".htaccess". If not, go to the Calendar Web Page Directory and change the name of the file we created called ".htaccess" to the name your Server expects.
 
 

System Settings that Can Cause Problems

System Clock

 Edit YourWorkingDirectory/Calendars/DATA/LastCheckTime
It should contain a large integer; changing this value to 1 will flush the email program, causing reminders to be sent for the current 24 hour period and synchronizing the email reminder program with your new clock settings.

NOTE: Year 2000 Testing Shared Calendars is Y2K compliant; however, if you test your system for Y2K by changing your system clock, you may have the following small problems:

• While testing, users will of course get reminders for events occuring in the year 2000: be sure to remind users not to rely on Shared Calendars for their current appointments.
• After testing, when you set you clock back, Shared Calendars will behave as if it has already sent reminders through the latest time that was ever on the system clock. See the section on the System Clock

If it doesn't work

Forbidden

Forbidden
You don't have permission to access /YourWebServer/apply.cgi on this server.

• Then what may have happened is that you answered the question: "Do your cgi programs run under this USER ID? ( Y/N ):" with 'Y', when your programs don't really run under the same USER ID. If you answered 'Yes', than makeconf sets up a tighter security system, which blocks out any users who are running under different USER ID's.

Try running makeconf again, answering that question 'No', or change the permissions yourself.
• It is also possible that your system sets "permissions" in a way that we did not expect: makeconf will set permissions as best it can, but make sure that your cgi programs run under a USER ID that has access to the cgi programs and the DATA section of the Program Directory.

Permissions

makeconf will set permissions as best it can, and for most systems sets them succesfully. Check to make sure that your cgi programs run under a USER ID that has access to the cgi programs created, and the DATA section of the main Program Directory.

* If you try to create a new calendar, like "Holidays", but the calendar does not appear, try to create it again. If it tells you that the calendar was already created, your problem involves Server Settings.

User List Error

Check to see if it knows your user name. If the user name is blank, that indicates there is either no security system, or the environment variable REMOTE_USER was not set.

If it does know your user name, then the error is that you set up your security system correctly, but when you ran makeconf, the correct username file was not entered. So, users can access the Calendar without being blocked by security, but the calendar can not find their name. Go to "Options.pl" in the main Program Directory, and fix the variables $UsersLocation and/or $SlitUsersWith.

Further Administrator Options

Changing The Look -- Additional Options

Additional Options

For example, you can change:

• the colors
• between reading the time in a twelve hour ( 3:00pm ) or twenty-four hour ( 15:00)
• the day that your weeks start on (typically Sunday or Monday)
• number of lines printed for each day, when viewing a month (less lines makes for a more compact calendar; more lines means all your events can fit on one page without "more" buttons.)
• and many more.

Changing the "< body >" tag, Adding Logos, Contacts, Messages

Making Changes to the Initial Configuration

Run "makeconf.cgi" again

Run makeconf.cgi again: it will configure a working Shared Calendar according to the latest answers you give, but will not erase previously created directories or files unless it writes over them. It will not remove the new directories created the first time, you may want to do that yourself. Also, it will not remove your first entry in "crontab", so you can just leave that running unless you make major changes. It should copy the original files into the folders you indicate this time, whether they already exist or not. It may clean out your DATA directory (events and users) and replace your data files with blank files. There are tricks for saving the DATA if you prefer, contact us.

Please make backups before trying this, especially if making major changes.

To remove unwanted users

Or, by hand:
The most important step is to remove them from your passwords file, wherever you keep it ( the default is "YourWorkingDirectory/DATA/Office/calendar.pwd" ). If you might let them back in later, you may want to stop here. To really remove them, delete their name from "Users" and "calendar.email" (in the same directory by default.) Then go into directory Lists, ( the default is "YourWorkingDirectory/DATA/Office/Lists" ), and remove the file with their name (which contains their Access levels to various calendars.)

Finally, decide if you want to remove any of the calendars they created. You can delete someone without destroying all the shared calendars that they created and that other people are now using. This is best done within the "Shared Calendars" program, logged in under "Admin", one calendar at a time.

Moving Web Pages

You can move the Web Pages.  First, decide where you will move things.  Then, using either the Options within Shared Calendars or the makeconf.cgi program, let Shared Calendars know where the programs will be.  Shared Calendars may stop working correctly after you do this, until you move the files.  For secure areas, be sure to move the security, along with the cgi and html files. Be sure to keep all files that start in a single directory together.
 

Making Changes to the Program

Little Changes

Do It Yourself

Contracting Through Us

Contact, Ordering and Registration

 Shared Calendars, Copyright 1998, 1999, 2000, 2001 by Boutell.Com, Inc., Inc. All Rights Reserved.

 Author: Stephen Cataldo, email cataldo@boutell.com