webcalng admin guide
webcalng version 1.1

Installation - Installing the webcalng software.
Configuration - Configuring webcalng for your site.
Administration - Performing administrative tasks in webcalng.
Integration and Customization - Integrating and customizing webcalng software for your site.
webcal 3.x - Converting calendar data from webcal 3.x to webcalng
Getting Help - What to do if you are having problems with webcalng.
Un-Installation - Un-Installing webcalng software.


Installation [Top]

Requirements. [Installation] [Top]
The webcalng software can run under any webserver that supports CGI (Common Gateway Interface) scripts. The webserver must have Perl installed on it. Perl is included with most distributions of Unix based operating systems, and can be downloaded for Microsoft based operating systems from ActiveState.

In addition to the standard Perl modules, webcalng requires the HTML::Template module to be installed on the webserver. Depending on the features of webcalng that you choose during install, some other non-standard Perl modules may be required as well. The installation program will detect if your webserver has the required modules, and alert you if any are missing. For Unix based operating systems, see CPAN for obtaining Perl modules. For Microsoft based operating systems, use the PPM (Perl Package Manager) application that comes with ActiveState Perl to install Perl Modules.

The webcalng software has been tested under Apache for Unix and Microsoft based operating systems, as well as under IIS for Windows 2000.

To use webcalng, a web browser is required. You do not need to have JavaScript enabled to use wecalng with the default theme, although certain sections of the application will be more functional if JavaScript is enabled. You need cookies enabled in your browser if you choose to use the default session based authentication. Cookies are not required if you choose to use htacess style authentication (available only for webservers running on Unix based operating systems).


Running the install script. [Installation] [Top]
Once you have a working Perl installation on your webserver, you can run the install script. Extract the webcalng software and "cd" into the directory containing the install.pl script (this must be done from a command shell on both Windows and Unix systems). Then run the installation program by typing "perl install.pl". The installation program should be run as the "root" user on a Unix platform, or a user with administrative priviliges on a Microsoft platform. See the Unix platform notes for more information about installing webcalng without root access.

The installation program will ask you a number of questions about how you want to setup webcalng. Simply follow the instructions on the screen, and answer the questions as appropriate for your webserver. If you make a mistake during the installation, don't worry - you can hit <CTRL-C> to interrupt the installation and start over. If you need to re-install the software due to a mistake in the initial install, this is OK too.

If you do not have command line access to the webserver on which you wish to install webabcalng, see the section on Installation on a hosting server with only ftp access.


Upgrading from a previous version of webcalng. [Installation] [Top]
Upgrading webcalng is easy. Simply install the new version right over the top of the existing installation, using all the same configuration information. Some issues to keep in mind:
  • You do not need to setup the webcalng reminder script again. You should answer no to the question of "Setup the cron job needed to use webcang reminders and notices" for Unix installations or the question of "Setup the Windows Service for webcalng reminders and notices" for a Windows installation. Assuming you already have the cron job or Windows service setup, the new webcalng reminder script will run correctly.
  • You do not need to reconfigure your database for use with webcalng. Simply provide the same values for all database related items such as database user, password, table prefix, etc. The new webcalng installation will use the data in your current database.

Authentication types. [Installation] [Top]
You can choose from 2 different methods by which webcalng will authenticate users:
  • session - Session based authentication uses web browser cookies to store a session key when you login. That session key identifies you to webcalng. This is the default authentication method. It has an advantage in that you can log out from webcalng without closing your web browser. However, some people like to disable cookies in their browser, in which case this would not work for them.
  • htaccess - Select htaccess style authentication if you do not want to use session based authentication with cookies. This will configure webcalng to direct users to a private directory protected with a .htaccess file using Basic authentication when authentication is required. You must close your browser to logout from webcalng when using htaccess style authentication. You can not use htaccess style authentication when installing on a Microsoft platform.
Either method usually works equally well, so stick with the default of session based authentication if you are unsure. One thing to keep in mind is that, if you plan on connecting to webcalng from a WAP enabled device, you must be using session based authentication.


Unix platform notes. [Installation] [Top]
When installing on a Unix platform, all permissions are automatically setup securely, if you are running the installation program as root. If you have trouble creating calendars after the install, make sure you gave the install program the correct username that your webserver is running as.

If you do not have access to the root account, you can still install webcalng. The installation program will warn you that you are not installing as root, and allow you to continue. You should be aware of the following issues when installing with a non-root account:
  • The data directory will be world writable (mode 777) if you are using flat files to store webcalng data. This is needed so that the webserver process can write to the database directory. When installing as root, the database directory would be changed to mode 700 and owned by the same uid that the webserver runs as.
  • Certain files in the data directory (such as the passwords, sessions, preferences, and messagequeue files) will be mode 666 if you are using flat files to store webcalng data. This is needed so that the webserver process can write to these files. When installing as root, these files would be changed to mode 600 and owned by the same uid that the webserver runs as.
  • The wecalng.conf file will be world readable (mode 644). This can be a security concern when using a relational database to store webcalng data, as the database username and password are stored in the webcalng.conf file. When installing as root, the webcalng.conf file would be mode 600 and owned by the uid that the webserver runs as.
If you choose to use htacces style authentication, you will need to make sure that your webserver is configured to allow authentication in the webcalng install directory. See the Configuration section of this document for more information.


Windows platform notes. [Installation] [Top]
The webcalng software has been tested under IIS, and Apache for Win32. When you intall ActiveState Perl, by default it will add the necesary configuration to IIS to enable it to run Perl scripts. You can only use session based authentication with cookies on a Windows platform.

After the webcalng software is installed, you need to make sure that the webserver process has the ability to write to the webcalng data directory, and the files underneath it. If you are using a SQL Server or Oracle database to store webcalng data, then the webserver only needs to be able to read from the webcalng data directory. By default, the webcalng data directory is C:\webcalng. If you are unsure what account your webserver runs as, you may want to just set the webcalng data directory and the files within it to "Everyone", "Full Control".

The installation program will ask you if you want to have a service added to enable support for webcalng reminders and notices. If you do not add this service, webcalng can not deliver email reminders and meeting notices. You will need to have the "srvany" and "instsrv" executables installed on the webserver in order to get the webcalng reminder script installed. After the installation is complete and the reminder script has been setup properly with registry changes in place, you should start the webcalng_reminders service on the webserver to enable reminders and meeting notices.

If you do not have the instsrv and srvany executables installed on the server at the time of the webcalng installation, just re-run the installation program once you have installed instsrv and srvany to get th webcalng reminders service configured. The webcalng installation program sets up the necessary registry entries for you. The path to the Perl executable and the path to the wecalng reminder script is needed. For example, if the default installation paths were used, the following registry keys would be setup:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\webcalng_reminders\Application = C:\perl\bin\perl
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\webcalng_reminders\AppParameters = C:\inetpub\scripts\webcalng\webcalng.pl -loop

The instsrv and srvany executables can be found in the Windows NT/2000 Resource Kit.


Flat file notes. [Installation] [Top]
No special configuration is needed if you choose to use flat files to store webcalng data. Each calendar will have a directory created for it in the database directory, and webcalng data will be stored there.


MySQL notes. [Installation] [Top]
No special configuration is needed to use MySQL for data storage with webcalng.

You have the option of letting the installation program create and populate the database for you, or just to create the necessary SQL scripts for you. If you are an experienced DBA, you may want to have the installation program only create the SQL scripts, and then modify the src/mysql/mysql_setup.sql script before running it to create the webcalng database.

If you are using MySQL to store webcalng data, you will need the DBI and DBD::mysql modules for Perl installed on your webserver.


PostgreSQL notes. [Installation] [Top]
In order for webcalng to properly connect to a PostgreSQL database, you must be using either "trust" or "password" authentication for the database. This is setup in your pg_hba.conf file. To use password authentication, you would need a "local" line like this:

local all password

If you were using trust or ident to connect to postgres as the postgres user, and are going to switch to password authentication to use webcalng, then you should first change the postgres password so that you can connect to the database with a password on the postgres account (which you may not have been using before). To do this, connect with psql and the postgres user, and run the following:

ALTER USER postgres WITH PASSWORD 'mypassword';

You have the option of letting the installation program create and populate the database for you, or just to create the necessary SQL scripts for you. If you are an experienced DBA, you may want to have the installation program only create the SQL scripts, and then modify the src/postgresql/postgresql_setup.sql script before running it to create the webcalng database.

If you are using PostgreSQL to store webcalng data, you will need the DBI and DBD::Pg modules for Perl installed on your webserver.


Oracle notes. [Installation] [Top]
If you are installing on a Microsoft platform, the installation program will create 2 SQL scripts that can be used to create the webcalng database in Oracle. These scripts will be in the src/oracle directory. The oracle_setup1.sql script should be executed as the system account in Oracle, and the oracle_setup2.sql script should be executed as the webcalng account that was created in oracle_setup1.sql. For example:

sqlplus system/manager@tnsname < src/oracle/oracle_setup1.sql
sqlplus webcalng/webcalng@tnsname < src/oracle/oracle_setup2.sql

If you are installing on a Unix platform, You have the option of letting the installation program create and populate the database for you, or just to create the necessary SQL scripts for you. If you are an experienced DBA, you may want to have the installation program only create the SQL scripts, and then modify the src/oracle/oracle_setup1.sql and src/oracle/oracle_setup2.sql scripts before running them to create the webcalng database. The oracle_setup1.sql script must be run when connecting with sqlplus as the system account, and the oracle_setup2.sql script must be run when connecting with sqlplus as the webcalng account.

No matter which platform you are using, your tnsnames.ora file needs to be setup correctly such that the webcalng software can connect to the Oracle database using the tnsname that you give to the installation program.

If you are using Oracle to store webcalng data on a Unix platform, you will need the DBI and DBD::Oracle modules for Perl installed on your webserver.

If you are using Oracle to store webcalng data on a Microsoft platform, you will need the DBI and DBD::ODBC modules for Perl installed on your webserver. In addition, you will need to setup a system ODBC datasource with the DSN name that you gave to the installation program. The webcalng software will use the ODBC connection to talk to the Oracle database.


Microsoft SQL Server notes. [Installation] [Top]
Using a Microsfot SQL Server database to store webcalng data is supported when installing webcalng software on a Microsoft platform. The SQL Server should be setup to allow password authentication. The installation program will create 2 SQL scripts that can be used to create the webcalng database in SQL Server. These scripts will be in the src/mssql directory. The mssql_setup1.sql script should be executed as the sa account in SQL Server, and the mssql_setup2.sql script should be executed as the webcalng account that was created in oracle_setup1.sql. For example:

osql -U sa -i src/mssql/mssql_setup1.sql
osql -U webcalng -i src/mssql/mssql_setup2.sql

You will need the DBI and DBD::ODBC modules for Perl installed on your webserver. In addition, you will need to setup a system ODBC datasource with the DSN name that you gave to the installation program. The webcalng software will use the ODBC connection to talk to the SQL Server database.


Installation on a hosting server with only ftp access. [Installation] [Top]
In order to configure webcalng for use on a hosting server that you only have ftp access to, you will need to have command line access to your own system with Perl installed on it. You will run the install script from your own system to configure webcalng, and then ftp the configured webcalng software up to your hosting server. This is done by running the install.pl script from your own system with a special option. If you run:

perl install.pl -ftp

The install program will proceed as normal, but a directory named "ftp" will be created in the same directory as the install.pl script. This ftp directory will contain all the webcalng software that should be transferred to the hosting server. The following conditions need to be met on the hosting server in order for webcalng to work properly:
  • The software must be installed at the same spot on the hosting server as you specified during the installation program.
  • You will still need to have all the necessary Perl modules installed on the hosting server.
  • Reminders and meeting notices will not work unless you get a cron job setup (for a Unix platform hosting server) or a windows service setup (for a Microsoft platform hosting server) on the hosting server to run the webcalng_remind.pl script.
  • After transferring the application to the hosting server, you will need to do a "chmod 777 data" from the ftp session in order to open up permissions on the data directory. This will leave permissions more open than would be desirable, but without root access there is no other way. You do not need to do this if you are using a relational database for storage.
  • If you are using a relational database for storage, you will need to get the database configured and populated using the SQL scripts created for your database platform during the install script.
If you do not have a system with Perl installed on it to use for configuring webcalng, please contact us at support@webalng.com. We will be able to gather information from you about your hosting server, and build a custom webcalng distribution for you to use on your hosting server.



Configuration [Top]

Configuring Apache for webcalng. [Configuration] [Top]
If you are using session based authentication, no configuration of the webserver is needed as long as the directory that webcalng was installed in has the ability to run CGI scripts.. If you choose htaccess style authentication, you need to make sure that the install directory has the ability to use htaccess style authentication. This would be an example of configuring Apache to use htaccess style authentication in httpd.conf:

<DIRECTORY /var/www/cgi-bin/webcalng>
    AllowOverride AuthConfig
</DIRECTORY>

If you have installed webcalng and used htaccess style authentication, but the authentication is not working, check the AuthConfig setting in httpd.conf.


Configuring IIS for webcalng. [Configuration] [Top]
No special configuration is needed to use webcalng with IIS as long as you allowed the ActiveState Perl installer configure IIS with the appropriate associations to execute Perl scripts.



Administration [Top]

Logging on as the admin user. [Administration] [Top]
To login as the admin user, simply click on the login link from the webcalng start page. The default password for the admin user is "admin". You should change this password as soon as possible. The admin user has the much more power than a regular webcalng user account, so you should not share this account with others who you would not want to have complete control of all calendars on the system.


Administrator preferences. [Administration] [Top]
By accessing the admin preferences from the webcalng start page, the admin user has the ability to control which preferences users are allowed to modify. In addition, the admin preferences serve as a default setting for preferences on new calendars. New calendars that are creating use the preferences as set in the admin preferences until the calendar owner changes any preferences which that owner has rights to change.

In addition, there is a special section of the admin preferences for things which only can be controlled by the admin user. These preferences take effect for the entire webcalng installation.


Adding and removing webcalng calendars. [Configuration] [Top]
The admin user has the ability to add or remove calendars from webcalng. Depending on how the administrator preferences are configured, anyone may be allowed to add a webcalng calendar. The admin user is always the only user who can remove calendars. When a calendar is removed, all meetings scheduled from that calendar are also removed.


Adding and removing webcalng users. [Administration] [Top]
The admin user has the ability to add or remove user accounts. Users can only add accounts for themselves during calendar creation, if they are allowed to create calendars per the admin preferences.


Modifying a webcalng calendar. [Section 3] [Top]
The admin user can change a calendar name, a calendar owner, or the type which a calendar is defined as. Be aware that meetings and reminders are tied to a calendar name, so renaming a calendar will invalidate all meetings and reminders setup from within the calendar. The items will still be present, but meeting and reminder information for that particular calendar will not be.


Language support. [Section 3] [Top]
All languages which webcalng has been translated to will be installed automatically. The language translation files are stored in the "language" directory of the webcalng installation directory. If you find any errors in a translation, you can edit the given language file to correct them.

Some language translations may have been provided by an end user of webcalng. You can get a free license for webcalng by translating webcalng to a new language. Before beginning your translation, be sure to contact us at support@webcalng.com to make sure no one else has already submitted a translation for your language.



Integration and Customization [Top]

Integrating webcalng with your sites authentication database. [Integration and Customization] [Top]
The webcalng authentication code is broken out from the main code to allow for easier customization. After installing webcalng, you will find two perl modules related to authentication - webcalng_auth.pm and webcalng_auth_io.pm. These modules contain subroutines needed to perform authentication. If you have a pre-existing user database and authentication system that you would like to use with webcalng, just replace the subroutines in these two modules with your own perl code to perform the same functionality.


Changing the layout of webcalng using themes. [Integration and Customization] [Top]
All the HTML generated by webcalng is driven by the HTML::Template module. The webcalng application has been designed so that multiple set of templates, or themes, can be used with webcalng. In addition to the default "Basic" theme, an example of a new theme called "NoBorders" is also supplied with webcalng to demonstrate this functionality.

If you would like to customize the look or layout of webcalng by editing the HTML, it is recommended that you create your own theme. Any directory within the themes directory of the webcalng installation is considered a theme if it starts with "webcalng.". The name of the theme is everything after the ".". Simply copy the webcalng.Basic theme to a new directory with a theme name of your choice. Then edit the HTML templates in your new theme directory. If you want to make sure that all calendars at your site use your theme, just choose your theme from the admin preferences, and then set that preference so that users can not modify it. If you want to force a color scheme for your theme, simply edit the css.tmpl file and hardcode your values in.



webcal 3.x [Top]

Converting calendar data from webcal 3.x to webcalng. [webcal 3.x] [Top]
If you had previously been using webcal version 3.03 from http://bulldog.tzo.org, you can convert the calendar data into webcalng format. After running the install program, a "util" directory will be created in the same directory as the install.pl script. Inside the util directory will be a script named "webcal3_to_webcalng.pl". This script can be used to convert calendar data from a webcal 3.03 calendar into a webcalng calendar. Here is an example usage:

# cd util
# ./webcal3_to_webcalng.pl   webcal3=/var/www/cgi-bin/webcal   from=public   to=test
Reading information from webcal3 calendar public.
Formatting data for webcalng.
Adding items to webcalng.
Copy from webcal3:public to webcalng:test complete.
#

If your calendar names have spaces in them, enclose them in quotes.

This would have copied the data from the webcal 3.03 calendar named "public" to the webcalng calendar named "test". Only the calendar items are copied, and you must have created the new calendar in webcalng before you can copy over data from the webcal 3.03 calendar.



Getting Help. [Top]

Problems installing or getting webcalng to run the first time. [Getting Help] [Top]
If you encounter errors during the installation of webcalng, please send a description of the problem and any error messages that your are getting to support@webcalng.com. In addition, a log file of the installation is created by the install.pl script. The log file is called install.log, and is located in the same directory as the install.pl script. Send the install.log file in along with your problem description and error messages to support@webcalng.com.


Reporting a bug. [Getting Help] [Top]
If you find a bug with webcalng, please report it to support@webcalng.com.



Un-Installation [Top]

Removing webcalng software from your system. [Un-Installation] [Top]
To remove the webcalng software from your system, simply remove the installation directory and database directory. For example, if you choose the default options on a Unix platform, webcalng software would be installed in /var/www/cgi-bin/webcalng and some webcalng data will be in /var/webcalng. Remove these directories. If you were using a relational database for webcalng data storage, see the relational database notes in this section.


Unix platform notes. [Un-Installation] [Top]
If you were using the webcalng reminders script, remove the entry for this script from your root crontab file.


Windows platform notes. [Un-Installation] [Top]
If you were using the webcalng reminders script, remove the webcalng_reminders service from windows. You can also remove the registry parameters entered for webcalng. The path to these registry entries is:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\webcalng_reminders


Relational database notes. [Un-Installation] [Top]
If you were using a relational database to store webcalng data, you can remove the database and webcalng user account. If you were using an Oracle database for webcalng data storage, you can remove the tablespace created for webcalng.



[Top]