SYNCHRONIZE
System Administrator’s Guide

Version 2.0

CrossWind Technologies, LLC.

Installing the Synchronize Client or Server for UNIX

Installation Summary
Installation Details

What to Install
Where to Install
Extracting the Software
Release Contents
Ownership of Files and Directories
Running the Installation Program
External Symbolic Links
Installing Only the Client Component
Installing Only the Server Component

After Installation
Upgrading
Changes to the Installation Procedure from Version 1.3

Installing the Synchronize Server for Windows NT

Overview
Installing from Floppy Disk
Installing from Downloaded File
After Installation
Upgrading

Installing the Synchronize Client for Windows

Overview
Installing from Floppy Disk
Installing from a Downloaded File
Upgrading

SYNCHRONIZE ADMINISTRATION

Users and Groups

Creating User Accounts
Designating Non-Human Resources
Modifying User Accounts
Disabling User Accounts
Deleting User Accounts
Designating a Synchronize Administrator
Synchronize Passwords
Hierarchical User Groups

Client Administration

Modes of Operation

Client-Server Mode
Stand-alone Mode

Time Zone Settings
Setting Default Configuration Options
Setting Default Calendar Permissions
Administrator-Imposed Options

Server Administration

Starting/Stopping the Synchronize Server for UNIX
Starting/Stopping the Synchronize Server for Windows NT
Server Options and Details

Overview
Options File Settings
Command-line Options for UNIX
Server Details
Multi-threaded Server Details

Setting Up Multiple Synchronize Databases

Overview
The Forwarding Agent
Starting and Stopping the Forwarding Agent
Groups Spanning Databases
Hosting Multiple Databases on the Same Machine
Limitations

E-Mail Administration

Overview
Client E-Mail Options
Server E-Mail Options
UNIX Sendmail and Trusted Users
Customizing E-Mail Notification

Database Administration, Utilities and Procedures

Backing Up the Database
Restoring the Database
Expiring Old Data from the Database
Moving the Database to Another Machine
Moving a User from One Database to Another
Splitting a Database into Two or More
Combining Databases
Import/Export of Users' Calendars

Performance Tuning

Server Performance
Client Performance

LICENSING

Applying a License to a Windows NT Database
Applying a License to a UNIX Database

---

INTRODUCTION

This guide describes the installation and maintenance of Synchronize^TM release 2.0 from CrossWind Technologies, LLC.

Synchronize is a real-time calendaring and scheduling application for corporations of all sizes. It is designed to support enterprise-wide collaboration among team members regardless of their individual locations. Synchronize’s advanced architecture makes it one of the most scalable applications in its category, offering enterprise collaboration from five to 50,000 users and beyond.

Synchronize’s advanced scalable design ensures that it will grow with the enterprise. Designed for cross-platform deployments, Synchronize 2.0 supports servers for Windows NT and over 20 UNIX platforms, as well as clients for Microsoft Windows, X11/Motif and character-based UNIX desktops. Its robust client/server architecture with distributed databases includes optimizations for multi-threaded architectures to enhance performance. Synchronize takes advantage of your existing servers and networks and does not require any special hardware or software to run. Because Synchronize 2.0 communicates directly across TCP/IP, access to critical information is instantaneous with none of the delays associated with file-based access methods, e-mail-based scheduling or slower transports.

Release 2.0 consists of various software components in three categories:

• Client components, which deal with the presentation of data to users;
• Agent components (specialized clients), which perform specific tasks on behalf of the Synchronize user or administrator;
• Database server components, which provide information to and perform actions on behalf of clients and agents when requested.

How to Contact CrossWind

If you have any questions or comments about Synchronize or about this guide, please call, e-mail or write to CrossWind Technologies, LLC.:

CrossWind Technologies, LLC.

835 Fern Ridge Rd
Felton, CA 95018
sales@crosswind.com
support@crosswind.com
http://www.crosswind.com
Phone: (831) 335-8351
Fax: (831) 469-1750

Supported Server Platforms

Synchronize servers are currently available for the following platforms:

• DEC Alpha (Digital UNIX 3.2 or higher)
• HP9000-300/400 (HP-UX 8.01 or higher)
• HP9000-700/800 (HP-UX 9.0 or higher)
• IBM RS/6000 (AIX 3.2 or higher)
• Linux
• Silicon Graphics (IRIX 4.X or higher)
• SunOS (4.1 or higher)
• Solaris for SPARC (2.4 or higher)
• FreeBSD (4.2 or higher)

Supported Desktop Clients

• UNIX/Motif clients are supported on all UNIX platforms listed above.
• UNIX/ASCII clients are supported on all UNIX platforms listed above except for the following:
  • DECstation (Ultrix 4.X or higher)
  • Linux
  • MIPS (MIPS ABI conformant OS)
  • Solaris for x86 (2.4 or higher)
  • Stratus (FTX 2.X)
  • UnixWare (2.X)
• Windows clients are supported on Windows 3.1x, Windows 95, Windows NT 3.5 or higher

  System Requirements

  Synchronize is a client-server application that uses TCP/IP for client-server communications. Remote file sharing (e.g., NFS, AFS, etc.) is not required (nor used) for database access. Any Synchronize client may access any Synchronize server regardless of the platform of either. To use Synchronize, you must have both a Synchronize server and a Synchronize client installed.

  UNIX	RAM	Disk space	Virtual memory	Other requirements
  Synchronize Server for UNIX	Minimum recommended by OS	3.5 MB* (including sample database)	500 KB per active user in the database	Disk and memory usage will increase over time depending on number of users and habits of use. 100MB per 100 users per year of use is a good rule of thumb.
  UNIX/Motif client	Minimum recommended by OS	5 MB*	2-4 MB per instance of client	X Windows version 11 Release 4, 5, 6
  UNIX/ASCII client	Minimum recommended by OS	2 MB*	2 MB per instance of client	VT or ANSI compatible terminal emulation (not all terminal types supported)
  Note: Synchronize for UNIX is distributed as a single 3 to 6 MB tar image (7 to 10 MB after installation) and contains both client and server software as well as a sample database. The amount of initial disk space required will vary depending on which components you choose to install. It is available as a tar image via FTP, on floppy disks, QIC, or 4mm DAT. (Not all media types are available for all platforms.) * varies by platform

  
  
  
  
  

  Windows	RAM	Disk space	Virtual memory	Other requirements
  Synchronize Server for Windows NT	24 MB	3MB	500 KB per active user in the database	Disk and memory usage will increase over time depending on number of users and habits of use. 100MB per 100 users per year of use is a good rule of thumb.
  Windows Client	8 MB	2.5 MB	4 MB per instance of the client	TCP/IP required: Winsock 1.1 or higher, Novell LAN WorkPlace or Microsoft LAN Manager (including HP ARPA services).
  Note: The Synchronize server for Windows NT and Windows client are each distributed on a single floppy or as a ZIP file available via FTP.

  
  

  ---

  
  

  INSTALLING SYNCHRONIZE

  Installing the Synchronize Client or Server for UNIX

  Installation Summary

  The following are the basic steps for installing the Synchronize UNIX software for the first time. Be sure to see the Installation Details section below for more information.

  1. Decide where you want to install the product and extract the software from the media provided into that directory.
  2. Run the installation script, i.e.

     sh ./INSTALL

     We recommend that you run the installation as root, although this is not strictly necessary.

  3. If you are installing Synchronize for multiple platforms in the same directory, repeat steps 1 and 2 for each platform you are installing. You must extract and install the software for one platform before extracting and installing the next.
  4. If you opted to install the Synchronize server component, edit the db/users file to add the users who will be using Synchronize. See the section on Users and Groups for details on how to do this. (You may choose to postpone this step and use the existing "Demo" account to use a sample Synchronize calendar.)
  5. If you opted to install the Synchronize server component, edit the Synchronize server startup script (bin/synchrod.sh), and then start the server by typing:

     bin/synchrod.sh &

     If you did not install the Synchronize server component, make sure that the Synchronize server will be running on some other machine.

  6. If you opted to install the client component, edit the bin/synchronize.sh client startup script setting the SYNCHROSERVER environment variable to the host name of the machine on which the Synchronize server will be running. This is the host to which the client will connect for database access. Also, if you have opted to use the SYNCHROPATH environment variable (see the section on Where to Install for details), you should also add it to the script at this time.
  7. At this point, you are done. Type synchronize to start the client application.

  Installation Details

  Synchronize is designed to be simple to install and maintain. Whether installing for a large or small number of users, it is helpful to plan ahead. The following topics will help you determine what details may be important when planning and executing the installation.

  What to Install

  All the files that make up Synchronize 2.0 for UNIX can exist in a single rooted hierarchy. The installation procedure gives you the option of installing the client component, the server component, or both in this hierarchy. The client component contains items such as:

  • client executable
  • client resource files (including X resource files)
  • other supporting files and software

  The server component contains items such as:

  • server executable
  • forwarding agent (for use with multiple databases)
  • common database

  The two components can be (and typically are) installed together in the same hierarchy. You may, however, maintain client software in a separate location from the server and database if your environment requires you to do so. The Synchronize installation procedure is designed to be very flexible in this respect.

  Where to Install

  Before you extract the release from the release media, you should decide where the Synchronize hierarchy will reside and which components (client, server, or both) should be installed. It typically makes for much easier administration if the software is installed in a single shared location that can be easily updated with new releases. You may instead opt to install the server software on a machine that will house the server and database, and install the client software in one or more locations on other machines. Make the directory owned by whichever user will own the Synchronize hierarchy. CrossWind recommends that the database be installed in a local file system on the machine where the server will run. If the server must access the database files on a remotely mounted file system (e.g., over an NFS mount), efficiency and data integrity may be compromised.

  Regardless of which components you have decided to install, Synchronize expects to find its hierarchy in $SYNCHROPATH, /usr/local/lib/synchronize, /usr/synchronize, or /synchronize. Each time it starts up, it looks in those four places (in that order) for a directory of that name (or a symbolic link pointing to a directory). The installation script will offer to create this symbolic link for you. Synchronize must find the hierarchy in one of these four expected places or it will not run. If the SYNCHROPATH environment variable is used, there will be no need to create any of the latter three directories, or symbolic links pointing to them. If you opt to use the SYNCHROPATH environment variable, you must set that variable to the correct path name of the Synchronize hierarchy before running Synchronize. The startup scripts in the bin subdirectory allow you to set this variable.

  Extracting the Software

  The following examples assume you have decided to install the Synchronize software in the directory /usr/local/lib/synchronize. Before extracting the software, perform the following two steps:

  1. Type the following command to create the directory where Synchronize will reside:

     mkdir -p /usr/local/lib/synchronize

  2. Change to the newly created directory:

     cd /usr/local/lib/synchronize

  Extracting from Tape or Floppy

  If the system on which you want to install Synchronize has a drive capable of reading the distribution media, follow these steps to extract the Synchronize software:

  To extract the software into the current directory, type:

  tar xf media_device

  Where media_device is your tape or floppy device name (for example, /dev/rmt0 or /dev/fd0).

  If the system on which you wish to install Synchronize does not have a drive that is capable of reading the distribution media, you will need to find some other system on the network that can. One way to read the distribution is to use a remote shell. Type the following to extract from a remote device after completing steps 1 and 2 mentioned above:

  remsh remote_system dd if=media_dev bs=10k conv=sync | tar xf -

  Depending on your system, you may need to use the rsh command instead of remsh to execute a remote shell.

  Extracting Multiple Releases from a Single Tape

  Some distribution media (tapes, in particular) may contain Synchronize releases for more than one platform. To extract the software for multiple platforms, use the examples above for the first file on tape. For subsequent files, use the mt command to skip forward on the tape. You must specify the non-rewind tape device for your system and how many files to skip as follows:

  mt -f non-rewind_tape_device fsf n

  (Use mt -t on HP-UX)

  where n indicates how many files to skip over from the beginning of the tape. Once the tape is positioned, you can use the examples in the Extracting From Tape or Floppy section above to extract the file. For example, if your tape contains Synchronize tar images for SunOS, HP800 and Solaris, in that order, and you wish to extract only the first two tar images, you would take the following steps after completing steps 1 and 2 mentioned above:

  tar xf tape_device

  The above command will extract the SunOS software that you must install before extracting the next tar image. After it’s installed, you would then type:

  mt -f non-rewind_tape_device fsf 1

  (Use mt -t on HP-UX)

  to skip forward one file from the beginning of the tape followed by:

  tar xf tape_device

  to then extract the HP800 software.

  Extracting from a Downloaded File

  If you have downloaded or obtained a Synchronize release tar file, you should complete steps 1 and 2 mentioned above, copy the tar file to /usr/local/lib/synchronize, and then type:

  tar xf tar_file

  to extract the contents of the file into the current directory.

  Release Contents

  The Synchronize release contains the following files and directories. During installation the .new suffixes are renamed or removed as necessary. Files or directories particular to either the client or server component are noted:

  File or directory	Description
  INSTALL	Installation script
  SYSADM	Synchronize System Administrator’s Guide (ASCII text)
  VER_version_arch	File indicating the release version and platform architecture
  bin.new/	Startup scripts and installation support scripts
  db.new/	Synchronize database and related files (Server component only)
  arch.new/	Platform-specific executables and support files
  ps.new/	Support files for PostScript® printing (Client component only)
  relnote	Release notes
  resources.new/	Synchronize resource files including X resource files, help and message catalogs (Client component only)

  Ownership of Files and Directories

  The installation will attempt to adjust ownership and permissions of files and directories as necessary to that of the specified Synchronize owner. It may not be able to do so if you do not run the installation as root or as the owner of the Synchronize hierarchy. It may be necessary to adjust ownership of the hierarchy manually before running the installation (especially if installing the release on a remote file system, e.g., over an NFS mount). The following command examples assume you are installing in the directory /usr/local/lib/synchronize and that you will specify bin as the Synchronize owner. If your system supports the chown -R command then:

  chown -R bin /usr/local/lib/synchronize

  will do the job, or, if your system does not support the chown -R command (e.g., SCO UNIX), then you might use the find command as follows:

  find /usr/local/lib/synchronize -exec chown bin ’{}’ ’;’

  Once ownership of the hierarchy is consistent throughout as the new Synchronize owner, then the installation should be able to complete without any problems. CrossWind recommends bin as the owner of the hierarchy in most instances. If installing the server and database component, then the hierarchy, however, must not be owned by root, as the database locking mechanism depends on this. The installation will not allow you to choose root as the owner when installing this component.

  Running the Installation Program

  The command sh ./INSTALL invokes the installation program. Only the system administrator (root) or the person who will be (or who already is) the Synchronize administrator should install the release. If you are installing Synchronize for the first time, then you must run the installation on the same type of machine for which you are installing. This is necessary for the license to be installed. When installing additional platform binaries or upgrading an existing hierarchy, then you may run the installation on whatever platform is convenient. This flexibility allows you to install releases for multiple platforms all in the same directory from the same machine. Remember when installing for multiple platforms to extract the files for the first platform into the Synchronize hierarchy and run the installation script. Then extract the files for the second platform in the same Synchronize hierarchy and run the installation script. Continue in this fashion until you are done with all the different platforms you have chosen to install.

  During the installation, you will be asked various questions. Each question that appears on the screen will typically be followed by a prompt listing valid responses, such as "y" for yes and "n" for no. For example:

  [y/n](n):

  Any response that appears in parentheses following the list of valid responses is the default response. Pressing only the Return or Enter key enters the default.

  You will be prompted as to which components of the software you wish to install. If you choose to install only the client software, then you should have already installed or plan to install the server software and database on some other machine. If you plan to run without a server, i.e., client-only mode, then see the section Client-only Mode in this guide.

  If you are installing Synchronize for the first time, then you will be prompted to enter your license number (except when installing only the client component). License installation requires executing the Synchronize binaries. Therefore, when installing for the first time, you must perform the installation procedure on a machine on which those binaries will run. In other words, if you are installing Synchronize for the first time and you are installing it for Solaris, then you must run the installation on a Solaris system so that the licensing step will succeed. If you are installing a release in a hierarchy to which a license has been previously applied, then you can run it on any supported platform that is convenient. For more information on licensing details, see the Upgrading and Licensing sections in this guide.

  If you are installing the release on a remote file system (e.g., over an NFS mount), then keep in mind that your identity on the local machine may not be the same as that on the remote machine. For example, the user root usually does not map to root over an NFS mount. Similarly, if your installation involves a SunOS system, you must take into account that the bin and sys accounts on such systems are typically reversed from that of most other systems. If you run the installation as root, then you will be prompted whether you are installing in a local or remote file system. If remote, then the installation will perform an su to the specified Synchronize owner while manipulating files in the remote file system. If the installation fails because it cannot adjust ownership or permissions, then first try to manually adjust the ownership as outlined in the section Ownership of Files and Directories above before proceeding.

  You will be prompted to specify the owner of the Synchronize hierarchy that you are installing. In most instances, CrossWind recommends the user bin as the owner. The recommended owner will appear as the default. You are free to choose any user to own the Synchronize hierarchy. If installing the server and database component, then you may not choose root as the owner. The database locking mechanism depends on this. If installing only the client component, then this restriction does not apply.

  The installation program will offer to create either one or three symbolic links for you depending on which components you are installing. These links are not strictly necessary in order for Synchronize to run but CrossWind recommends that they exist to ease administration. See the section External Symbolic Links below for details. After the installation has been completed, the installation program can be run on other machines to create the necessary symbolic links so that Synchronize can be executed there.

  At this point, the installation will be complete. If the script fails to execute to completion it will issue pertinent error messages and terminate. After corrective action has been taken, the script may be restarted. Although the installation takes care to compose itself in the event of a failure, you may need to re-extract the release before re-running the installation program.

  External Symbolic Links

  The Synchronize installation will offer to create the following external (to the Synchronize hierarchy) symbolic links for you. The existence of these links is not strictly necessary, but will facilitate the execution of Synchronize and probably make Synchronize administration easier. Alternatives to creating these links are noted below. If you choose to create the links at a later time, or if you want to set them up on for a machine which will be accessing the hierarchy over the network (e.g., over an NFS mount), then you can simply run the installation script again with nothing new to install and it will skip directly to that step. These links should exist on any machine(s) on which Synchronize will be executed.

  • /usr/local/lib/synchronize ¾ > .
    Link to the Synchronize hierarchy (could also be /usr/synchronize or /synchronize). If the SYNCHROPATH environment variable is used then this link is not needed. This link applies to both client and server components.
    
    
  • /usr/local/bin/synchronize ¾ > bin/synchronize.sh
    Command name typed by users to start the Synchronize client application. This link should exist in a directory included in a user’s PATH environment variable (could be in some other appropriate directory, e.g., /usr/bin/X11). This link only applies to the client component of the software.
    
    /usr/lib/X11/app-defaults/Synchronize ¾ > resources/Synchronize
    Link to the Synchronize client X resource file. You can also use environment variables such as XFILESEARCHPATH or XAPPLRESDIR if you prefer to not use the link. This link only applies to the client component of the software.

  Installing Only the Client Component

  The installation script optionally allows you to install only the client component of the software. Use the installation summary above for installing the UNIX software with the following exceptions:

  • You will not need to edit the db/users file. This step should be completed on the system (UNIX or Windows NT) where you install the server software and database.
  • You will not need to edit the bin/synchrod.sh server startup script. This step should be completed on the machine where you install the UNIX server software and database.

  Client-Only Mode

  For the sake of backward compatibility, the Synchronize 2.0 release supports what is termed "client-only mode." When run in this mode, each instance of the Synchronize UNIX client manipulates the common database directly either through the local file system or on a remote file system. The Synchronize server is not used in this mode. Operating in client-only mode precludes you from running other clients (e.g., Windows) against this database as they require a Synchronize server. It also precludes you from setting up multiple Synchronize databases that share calendaring information, as a server is required in this case also. CrossWind Technologies does not recommend that you run in client-only mode unless you do not have network access to a Synchronize server. If you must run in this mode, then the following additional details will apply to you:

  • To install the software for client-only mode operation, choose to install only the client component when prompted by the installation and answer no to the question asking if you plan to install the server somewhere on your network.
  • The Synchronize client must run as a setuid process. It is installed this way by default when you answer no as specified above. As a result, if the database hierarchy is mounted as a remote file system (e.g., database access is over an NFS mount), then the mount must be done with the read/write and setuid options enabled. If, when attempting to run Synchronize, you receive errors that certain files are not writeable, then the likelihood is high that the client binary is not setuid or that the remote file system is not mounted with the correct options.
  • You must not have a Synchronize server operating on the same database. In other words, the database should be accessed by clients in a consistent manner.

  Installing Only the Server Component

  Use the installation summary above for installing the UNIX software with the following exceptions:

  • You will not need to edit the bin/synchronize.sh client startup script since it will not have been installed.
  • You will be prompted to create only one symbolic link. The other links mentioned in the External Symbolic Links section are only applicable to the client component.

  All other steps mentioned in the summary and details above still apply.

  After Installation

  If you have installed the server and database component of the release, then for convenience you may wish to change the ownership or group of certain files that you will need to occasionally modify in the course of maintaining Synchronize. These files are as follows:

  db/users
  db/groups
  db/groups/*
  db/domains
  db/database/server/*.opts

  It is not strictly necessary that they be owned by the Synchronize owner, but they must be readable by the Synchronize server. If you change the ownership of these files to another user (such as yourself), then you can more easily modify them when necessary.

  The installation program can be used to set up symbolic links on client machines that will be accessing the Synchronize hierarchy. When the script is run in a hierarchy where there is nothing to install, it simply asks if you wish to set up the symbolic links. This is useful when you have a single installation location which users access in a shared directory but will run Synchronize locally on their own machines. Remember that you can also set the environment variables mentioned in the External Symbolic Links section above in the bin/synchronize.sh client startup script.

  Be sure to see the section on Client Administration in this guide for information on default configuration settings for the UNIX/Motif client.

  Upgrading

  The installation procedure will never modify or damage the contents of your existing database. In addition, it attempts to modify or replace as few files as possible that may have been previously changed by the Synchronize administrator. For example, the Synchronize client start-up script (bin/synchronize.sh) is almost never replaced and the resources directory is replaced (and the existing directory renamed to resources.old) only when absolutely necessary. As a result, you should not hesitate to extract and install new releases of Synchronize on top of existing ones, when such installation is warranted. In all cases, the directory containing the platform specific binaries (e.g., solaris, rs6000, etc.) for which you are installing will be renamed with a .old suffix and a new directory will be created for the new release.

  The following are the basic steps you should take when upgrading Synchronize to a new version or when adding software for a new platform to an existing installation:

  1. If you are updating a directory containing the server and database component, stop the Synchronize server operating on that database before beginning the update.
  2. Extract the software from the media provided into your existing Synchronize directory. Newly extracted directories will have a .new suffix to distinguish them from your existing release.
  3. Run the installation program just as when installing a new release.
  4. Restart the Synchronize server if you stopped it in step 1.

  After the upgrade is complete, the following files will have been added/updated in your hierarchy and represent the distributed versions of the files with the same name (minus the .dist suffix).

  bin/synchronize.sh.dist
  bin/synchrod.sh.dist
  db/database/tztab.dist
  db/database/client.opts.dist
  db/database/macprefs.dist
  db/database/server/server.opts.dist
  db/database/server/router.opts.dist

  The files listed above may be periodically updated by CrossWind with fixes or new configuration options.

  Changes to the Installation Procedure from Version 1.3

  There are two notable changes to the version 2.0 UNIX installation procedure over version 1.3 and earlier:

  • The installation procedure now allows you to choose which components of the software to install: client software, server software, or both. The 1.3 installation required you to install both.
  • Installing a Synchronize release on the particular platform for which it was intended is no longer required (except when installing and licensing a server and database for the first time). In other words, when installing for multiple platforms in a single shared directory, you may run the installation script for each release on the same machine regardless of its architecture.
    

  ---

  Installing the Synchronize Server for Windows NT

  Overview

  The Windows NT installation procedure is executed through a standard graphical interface. The Synchronize server will be installed by default in \SYNCHRO\SERVER on your hard drive. You may choose to install in any other directory accessible on the system (except network drives). Most references to file and directory paths in this guide use the UNIX convention of forward slashes (e.g., db/users). You can safely substitute back slashes for any of these references (e.g., db\users) when working with the Synchronize server for Windows NT. All file and directory locations are identical between Windows NT and UNIX. Any exceptions to this rule are explicitly noted in their respective sections of this guide.

  Installing from Floppy Disk

  1. Start Windows NT and log on as an administrator (or a user with administrative privileges).
  2. From the Program Manager or File Manager select File->Run... (if you are running Windows NT 4.x, click the Start button and select Run…).
  3. Type: a:\setup or b:\setup (whichever is appropriate) and click OK. If you downloaded the software as a ZIP file, extract the contents of the ZIP file into a temporary directory (e.g., c:\temp) and then type the path to the setup program (e.g., c:\temp\setup).
  4. The installation procedure will ask you some routine questions and require you to enter your Synchronize license number.
  5. You are done and the Synchronize server will have been automatically started by default. See the After Installation section below.

  Installing from a Downloaded File

  If you have obtained the Synchronize Windows NT server software as a ZIP file, simply extract the software into a temporary directory on your system using PKZIP, WinZIP or other compatible utility. Then, follow the instructions starting from step 1 in the Installing from Floppy Disk section above.

  After Installation

  The installation procedure installs the Synchronize server as a Windows NT service. The service can be stopped and started from the Services icon in the Windows Control Panel. The server will be listed as "CrossWind Synchronize Server." The installation procedure will also create a new key in your Windows NT registry under the pre-defined HKEY_LOCAL_MACHINE\SOFTWARE\ key. The new key will be created as CrossWind Technologies\Synchronize Server\Current Version\. There are three value entries created under this key. They are as follows:

  License

  Your license string. You can modify/update your license by editing this entry.

  SYNCHROPATH

  The installation location. The Synchronize server for Windows NT uses the value of this entry to locate the database files.

  Version

  The currently installed version. You should not change the value of this entry.

  A Synchronize account with a login of "demo" is provided in the sample database shipped with Synchronize. If a user does not have an entry in the .\db\users file, then the user can log in as "demo" to use a sample Synchronize calendar. See the section on Creating User Accounts to add users.

  Upgrading

  You must stop the Synchronize server before beginning an upgrade. The procedure for upgrading is similar to that for installing, with the following exceptions:

  • The installation program will detect your existing installation and confirm your intent to upgrade.
  • You will not be prompted to enter a license, rather it will use your existing one.
  • You will not be prompted to specify the startup type for the service. Your previous setting will be used.
  
  

  ---

  Installing the Synchronize Client for Windows

  Overview

  The Windows installation procedure is executed through a standard graphical interface that asks a few simple questions and installs the software with little fuss. You will be asked as many as three questions:

  • Where do want Synchronize to be installed?
  • Which TCP/IP stack will you be using?
  • What is your time zone? (if not already set)

  If you are not sure which TCP/IP stack you are using, choose the Winsock 1.1 option. In most cases this will be the correct choice. The default directory into which the Synchronize Windows client will be installed is C:\SYNCHRO\CLIENT. The default directory for previous releases of Synchronize was C:\SYNCHRO. You may choose to install in any other directory accessible on that system (including network drives). Be sure to see the section on Client Administration in this guide for information on default configuration settings for the Windows client.

  Installing from Floppy Disk

  1. Start Windows.
  2. From the Program Manager or File Manager select File->Run... (if you are running Windows 95 or Windows NT 4.x, click the Start button and select Run…).
  3. Type: a:\setup or b:\setup (whichever is appropriate) and click OK. If you downloaded the software as a ZIP file, extract the contents of the ZIP file into a temporary directory (e.g., c:\temp) and then type the path to the setup program (e.g., c:\temp\setup).
  4. After the installation procedure has completed, you are done. See the Synchronize User’s Guide for instructions on how to run and configure the Windows client. You can safely delete the contents of any temporary directory you created for the Synchronize installation.

  Installing from a Downloaded File

  If you have obtained the Synchronize Windows software as a ZIP file, simply extract the software into a temporary directory on your system using PKZIP, WinZIP or other compatible utility. Then follow the instructions starting from step 1 in the Installing from Floppy Disk section above.

  Upgrading

  The procedure for upgrading is exactly the same as for installing. The old software will be automatically replaced by the new and your existing configuration will be preserved. One notable change is that the default installation directory is now C:\SYNCHRO\CLIENT. In previous releases, it was C:\SYNCHRO.
  

  ---

  A Simple Installation Example

  The following example offers a simple scenario that may help you in setting up Synchronize. Keep in mind that the installation procedure is very flexible and you may modify this example to suit your needs.

  The Example Environment

  XYZ Corporation is a public relations firm that employs about 25 people. Each employee has a PC on their desk running Windows 95 and the company owns a Sun SPARC 5 running SunOS called "soapstone" that serves as both a file server and as their Internet e-mail server. The company has decided that soapstone will host the Synchronize server and database and that the users will install the Windows client on their desktop PCs.

  Setting Up Synchronize for the Office

  The administrator for XYZ Corporation, Nelson, has decided that he will install Synchronize in /usr/local/lib/synchronize on soapstone and completes the following steps:

  • First Nelson logs in to soapstone as root and creates the /usr/local/lib/synchronize directory. He then extracts the Synchronize release for SunOS and runs the installation program opting to install only the server component.
  • After the installation has successfully completed, Nelson sets up the users’ accounts according to the instructions in the Users and Groups section of this guide. Also, he edits the bin/synchrod.sh script and then executes this script to start the Synchronize server on soapstone.
  • Nelson then distributes copies of the Synchronize release for Windows on floppy disk for the users to install the client software on their computers.
  • Each user in the office runs the Synchronize setup program on the floppy and installs Synchronize using the default installation options. After installation, each user starts the application by double-clicking on the Synchronize icon. When prompted, each user enters "soapstone" as the server and types their Synchronize login (as entered by Nelson in the db/users file on the server). Since this is the first time running the application, each user will be prompted to set a new Synchronize password before accessing their calendar.

  XYZ Corporation is now up and running with Synchronize.
  

  ---

  A More Complex Installation Example

  The following example covers a broad range of scenarios. You can use this example in its entirety, or pick and choose which parts may apply to you. Keep in mind that the installation procedure is very flexible and you may modify this example to suit your needs.

  The Example Environment

  ABC Company designs, manufactures and markets its own line of gadgets. The company occupies three sites, Research and Development, Manufacturing and Sales and Marketing, each in a different city. Each of these sites is connected on the company’s network. The company has decided that each site will have their own Synchronize database and that users from each site should be able to use Synchronize to schedule users in the other sites, too. Site specifics are as follows:

  • Research and Development consists of only UNIX users. Each user has their own UNIX workstation except for a few users who have X terminals on their desks. Systems on which Synchronize will be run vary between Solaris SPARCstations and HP-UX 700 series workstations. The system that will host the Synchronize server and database is an HP 700 series server called "topaz." In addition to the server software and database, the Synchronize client software will be installed all in the same hierarchy where users will access the client binaries over an NFS mount. The X terminal users all share a common Solaris system called "brimstone" on which they run their applications.
  • Manufacturing is a mixture of UNIX servers and workstations (HP-UX and Solaris) as well as Windows NT servers and various Windows desktop systems. This site has decided that their Synchronize server and database will be hosted by their Windows NT server called "bauxite." The Manufacturing site also has an HP-UX file server called "mantle" on which UNIX applications are installed and accessed via NFS from the various UNIX workstations.
  • Sales and Marketing consists of Windows users. This site has a Solaris server named "tetraploid" that will be used to host the Synchronize server and database.

  Setting Up Synchronize at Each Site

  Research and Development Site

  The administrator at this site, Edith, has chosen to install Synchronize in the directory /shared/apps/synchronize on topaz. The /shared directory on topaz is already shared (exported) since users access other applications and documents installed under /shared.

  • Edith starts by becoming root and creating the /shared/apps/synchronize directory on topaz and extracting the Synchronize release for HP-700/800 into that directory. Next she runs the installation program on topaz and chooses to install both the client and server software there. The installation program proceeds, prompts for the new license, creates the recommended symbolic links and finishes successfully.
  • Edith then extracts the Synchronize release for Solaris in the same directory and runs the installation script choosing to install only the client software for Solaris since the server software is not necessary. The software for both platforms now coexists in the same hierarchy.
  • Next she sets up the users and groups for her department according to the instructions in the Users and Groups section of this guide.
  • Now Edith edits the bin/synchronize.sh and bin/synchrod.sh startup scripts. The bin/synchronize.sh script will be executed by all UNIX users regardless of which platform on which they are running. The bin/synchrod.sh script will be executed on topaz to start the Synchronize server daemon.
  • After consulting with the administrators at the other two sites and learning which systems will host their Synchronize servers, she sets up the db/domains file with the following entries:

    r&d, topaz, Research & Development
    mfg, bauxite, Manufacturing
    sales, tetraploid, Sales and Marketing

    After finishing, she shares her work on the db/domains file with the administrators of the other two sites. They can use a copy of the same unmodified file when setting up Synchronize at their sites.

  Now that Edith has finished setting up Synchronize on topaz, she must enable users to run the client application from their own systems.

  • First, she logs in to brimstone as root. Brimstone is the Solaris system where the X terminal users will log in to run Synchronize. Brimstone already NFS mounts the /shared directory on topaz as /network/topaz.
  • Next, Edith changes directories on brimstone to /network/topaz/apps/synchronize. This directory contains the Synchronize hierarchy that was created on topaz. Since the software for Solaris has already been installed here, she only needs to set up the recommended symbolic links on brimstone so that users can run Synchronize. She does this by running the installation script on brimstone in this directory, but since there is nothing new to install, it only prompts her to set up the links.

  For each system on which Synchronize will run, Edith does exactly what she did on brimstone, i.e., she logs in as root and sets up the symbolic links. Users now can type synchronize at their shell prompt to run the application. When upgrading to a new release of Synchronize, Edith needs only to extract and install into the existing hierarchy on topaz in order for all users to be upgraded.

  Manufacturing Site

  The administrator at this site, Sam, has decided to install the Synchronize server and database in the default directory C:\SYNCHRO\SERVER on bauxite, their Windows NT system.

  • Sam logs in as an NT administrator and runs the setup program provided in the Synchronize release. The installation proceeds, prompts for this site’s license and finishes successfully.
  • Next Sam sets up the users and groups for his department according to the instructions in the Users and Groups section of this guide.
  • He also copies the db\domains file which was given to him by Edith from the R&D site.

  Now that Sam has finished setting up Synchronize on bauxite, he must enable users to run the client application from their own systems. He starts first with the UNIX users.

  • First, he logs in to mantle, the HP system, as root and installs the client software only first for HP-UX and then Solaris in a directory called /netshare/synchronize. The /netshare directory is an exported NFS directory to which all UNIX systems at this site have access. Since he is installing only the client software, he will not be required to enter a license for this installation.
  • Sam then edits the bin/synchronize.sh client startup script that all UNIX users will run.
  • Each UNIX workstation at the Manufacturing site NFS mounts the remote /netshare directory on mantle as /netapps. Sam logs in as root to each workstation that will run the Synchronize client application, changes directories to /netapps/synchronize and runs the installation script to set up the symbolic links for each.

  Now the UNIX users may simply type synchronize at their shell prompt to start the application. Next Sam sets up the Windows users.

  • Since each Windows user is responsible for maintaining their own applications on their computer, Sam simply makes the Synchronize Windows release available to them (either on floppy or on a shared network drive) to install. He gives them instructions on setting their time zone variable appropriately and to specify "bauxite" as the server when logging in for the first time.

  Sales and Marketing Site

  The administrator for this site, Wayne, has decided to install the Synchronize server and database in /usr/local/lib/synchronize on tetraploid, their Solaris host. He has also decided to install the Windows and Mac software each in a single location to make upgrades easier. The Windows and Mac systems all use some form of network file sharing and consequently have access to network file servers on which the software will be installed.

  • Wayne first creates the /usr/local/lib/synchronize directory on tetraploid and then extracts the release for Solaris there. He then runs the installation script as root and opts to install only the server component of the software.
  • After entering his Synchronize license and completing the installation, Wayne sets up the users and groups for his department according to the instructions in the Users and Groups section of this manual.
  • He then copies and uses the db/domains file which was given to him by Edith at the R&D site.
  • Wayne also edits the bin/synchrod.sh script that he subsequently uses to start the Synchronize server.

  Now that the server is set up, he must set up the client software for the Windows users.

  • First, Wayne decides to install the Windows software in a shared network directory on the UNIX server. The directory /shared/pcapps on tetraploid is a read-only NFS exported directory. All Windows users have NFS software installed, and they each have access to this shared directory as drive M:\ on their computers.
  • Wayne first installs on his own PC in the default C:\SYNCHRO\CLIENT directory, runs Synchronize and sets up the default configuration options (e.g., time zone) through the Options -> Configuration window.
  • He then creates the /shared/pcapps/synchro directory on tetraploid and copies the contents of his C:\SYNCHRO\CLIENT directory there. He also copies his C:\WINDOWS\SYNCHRO.INI file there (overwriting the default) since that is where changes to the configuration options were saved.
  • Wayne now announces to the PC users that they should create an icon for the M:\synchro\wsync.exe file and set the working directory for this icon to M:\synchro. Users will see "tetraploid" already filled in as their server when logging in for the first time since that was saved during Wayne’s initial setup. Users now just double-click on the new icon to start the application.
  
  

  ---

  SYNCHRONIZE ADMINISTRATION

  Users and Groups

  Creating User Accounts

  Once Synchronize is installed, you should edit the db/users file with a text editor and enter the names of the users who will be using Synchronize. User names can be entered in any order and sorted by the Administrator for convenience. The order in which names appear in the users file is the order in which they will be presented to users. Entries should be added with the following format:

  Synchronize_name, login_name, e-mail_address, Synchronize_alias

  The above fields are defined as follows:

  Synchronize_name

  This field is the user’s Synchronize name. It is mandatory and must also be unique within the database. Once entered and used, this field must never change. If it changes, Synchronize will not be able to find the calendar items for that user and all entries for that user will have been lost. Use the optional Synchronize_alias field (see below) to change a Synchronize user’s name once it has been established.

  login_name

  This field is required for all Synchronize users and should be unique within the local database. This field should be left blank for "non-human" resources like conference rooms. For UNIX users, this field contains their unique UNIX login. For non-UNIX users, this field can be anything (i.e., non-UNIX users do not need to have a UNIX login to run Synchronize). This field can be changed at any time to reflect a new login.

  e-mail_address

  This field is optional, and is used to designate an e-mail address for the user. If this field is omitted, then the login_name will be used by default as the e-mail address. This field is typically necessary when the e-mail system needs more information than just the login_name to route e-mail correctly. If the Synchronize server is running on a Windows NT host, then you may optionally prefix the user’s address with MAPI:. Doing so indicates that any e-mail to this user must be sent specifically through the MAPI system.

  Synchronize_alias

  This field is optional, and determines how the user’s name will be displayed within Synchronize. If this field is omitted, then the Synchronize_name is used by default. This field can be used or modified, for example, when a user changes his or her name due to marriage. To avoid confusion, it is suggested that you not use a name that conflicts with another local Synchronize_name or Synchronize_alias, although this is not strictly required.

  Fields (including blank fields) must be separated by commas. Any extra white space before or after a comma is optional and will be ignored. If a particular field contains a comma, then you must surround the entire field with double quotation marks so that the comma will not be interpreted as a field separator. You should take care to hit Return or Enter at the end of the last line in the file. Most of the time it will not be a problem, but some text editors fail to automatically include an end-of-line character before the end-of-file thereby causing the last line to be ignored. Here is an example of entries in the db/users file:

  Joe, jclark, , Joey
  +Larry,lsmith,lsmith@mantle,
  Rhonda, rjones, , Rhonda Jones
  "Karlsen, Jim", jkarlsen,,Jim
  Joseph, joe,, Joe
  Conference Room A,,,
  Slide Projector

  Note: The leading "+" for Larry indicates that he is a Synchronize administrator. See the Designating a Synchronize Administrator section below for details.

  Designating Non-Human Resources

  As you can see in the above example, you can also list resources such as conference rooms and slide projectors in the db/users file. Users running Synchronize can then specify not only which users they would like to attend a meeting, but what resources they would like to reserve as well. Note that resource entries do not include a login_name. These entries are designated by the lack of a login_name. They are treated by Synchronize in much the same manner as other users, with the following exceptions:

  • Schedules for resource entries can always be opened by users, although individual items on the resource’s calendar may not be readable.
  • Synchronize administrators (see below) automatically obtain agency status for resources so that calendar permissions can be set easily for the resources.

  Modifying User Accounts

  There will commonly be times when a user’s entry in db/users must be modified. Any of the last three fields for an entry can be modified without loss of data for that account. Please remember, the first field for a user’s entry must not be changed unless you wish to remove the data for the original entry. For example, if a user changes his or her name, or is replaced by a different person, this change can be applied to the Synchronize_alias field in that user’s entry. If a user’s login_name must be changed, simply change that field. The e-mail_address field can be also be changed in this fashion. If you need to have a new user inherit data from another user’s calendar, consider simply changing all fields except the Synchronize_name. If you absolutely must modify the Synchronize_name, you can use the sy_mover utility to accomplish this. See the section on Database Administration, Utilities and Procedures in this guide for more information on sy_mover.

  Disabling User Accounts

  You can disable a Synchronize account without removing the calendar data associated with it. You can use any of the following techniques depending on your needs:

  • Clear or change the login_name to prevent anyone from logging into that account.
  • Change the Synchronize_alias to something (e.g., "disabled account") that will dissuade others from scheduling this account.
  • Prevent others from scheduling this account through restrictive settings in the Options -> Calendar Permissions dialog.

  Deleting User Accounts

  To delete a user account, you can either remove the user’s entry from the db/users file or change the Synchronize_name field. Please note: Deleting an account will automatically delete all calendar items originated by that user and removes that user from the invitee list of all calendar items to which he/she was invited. Extreme caution should be used when performing this type of maintenance.

  Designating a Synchronize Administrator

  Synchronize administrators can be designated by an optional "+" entered just before the Synchronize_name (see example above). The "+" is not part of the user’s name. One or more administrators may be designated for a database. Administrative capabilities apply only to the local database, not to remote ones. Administrators have the following capabilities:

  • Automatic agency status for resources: This facilitates the setting of calendar permissions for resources. For example, if you wish to designate Joe as the only person who can schedule a conference room, make sure that you are a Synchronize administrator, become the agent for that conference room (see the Synchronize User’s Guide for information on how to do so), and designate Joe as the only "Scheduler" for the conference room.
  • Maintenance of system level configurations: These include Holidays, Categories and Attributes. See the Synchronize User’s Guide for information on these features.
  • Ability to run Synchronize utilities to maintain the database: A number of utilities are available with the 2.0 release, including a utility to move a user’s data from one database to another (sy_mover) and a utility to purge old data from a database (sy_expire). See the Database Administration, Utilities and Procedures section for more information.

  Synchronize Passwords

  Synchronize passwords are optional for UNIX users and mandatory for Windows users. Listed below are some details to keep in mind when working with Synchronize passwords.

  • Windows users accessing their calendars for the first time will be prompted to enter a new Synchronize password.
  • If a user attempts, from a Windows client, to access his or her calendar which had been previously accessed from a UNIX client (and no Synchronize password was ever set), then either the user must first set a Synchronize password from a UNIX client, or you must reset the user’s Synchronize password (see below) before the user will be able to access his or her calendar.
  • A user (any platform) is not allowed to log in to a UNIX user’s Synchronize calendar if that UNIX user has not set a Synchronize password. Only that UNIX user (or anyone who can log in to that user’s UNIX account) can access his or her calendar.

  In some cases, it may be necessary to reset a password if, for example, a user forgets his or her password. To reset a password, the user’s password entry must be deleted from the db/database/userinfo file. There may be more than one line corresponding to the same user in this file. Only the line containing the encrypted password entry should be deleted. The entire line must be deleted.

  Hierarchical User Groups

  As the number of Synchronize users grows, a linear set of names becomes insufficient to allow quick access to users. To deal with this issue, the ability to display a hierarchy of user groups is provided. The db/groups subdirectory can contain files and directories that define the group structure. Files are used to designate group names and directories are used to designate group hierarchies. Group names must be unique within a particular database. This applies to both file and directory names. For example, you cannot have a group named "staff" under both Engineering and Administration (rather you could use "Engineering_staff" and "Administrative_staff"). Behavior is unpredictable if this rule is not met. Note that when using multiple databases (see the Setting Up Multiple Synchronize Databases section), you need only avoid identical group names within a single database. Groups with identical names in different databases will not conflict. The following example shows a possible layout for a groups hierarchy under db/groups:

  Building-1 (subdirectory)

  Engineering (subdirectory)

  Development (file)
  Pubs (file)

  Manufacturing (file)

  Building-2 (subdirectory)

  Administration (file)
  Marketing (file)
  Sales (file)

  A group file lists either the Synchronize_alias or Synchronize_name of users in the group, one per line. For example, if Joe, Jim and Rhonda (as specified in the example db/users file above) work in the Manufacturing group in Building-1, then the file db/groups/Building-1/Manufacturing might contain the following entries:

  Joe
  Karlsen, Jim
  Rhonda Jones

  Note that it is not necessary to surround Jim’s name by double quotation marks as in the users file. Also note that a group file entry will always refer to a matching Synchronize_alias before a matching Synchronize_name. For example, "Joe" in the above group file refers to the user whose login is "joe", not "jclark".

  UNIX users can create their own personal groups. This feature is not currently supported in the 2.0 Windows client. The procedure and rules for creating personal groups are the same as that described above for system groups with the following exceptions:

  • UNIX users must create the subdirectory .synchronize/groups in their home directory ($HOME) which will contain groups files and subdirectories. The .synchronize subdirectory may have already been created for them automatically by Synchronize.
  
  

  ---

  Client Administration

  While maintaining the Synchronize client software, the following topics may be helpful to look at from time to time.

  Modes of Operation

  All Synchronize 2.0 clients can run in two modes: client-server or stand-alone. Stand-alone mode is also sometimes referred to as detached or nomadic mode. Details of each mode are as follows:

  Client-Server Mode

  Users will most often or always run Synchronize in client-server mode. When operating in this mode, all database access occurs over your network with a Synchronize server running on a UNIX or Windows NT host. For the Windows client, you must specify the server host in the login dialog when logging in. For UNIX clients, there are two ways to specify the server host:

  • The SYNCHROSERVER environment variable is commonly set in the bin/synchronize.sh client start-up script. See the script itself for details.
  • The -server command-line option allows you to specify a server host and will override the SYNCHROSERVER environment variable (if set). You must specify a hostname with this option, e.g.,

    synchronize -server hostname

  Stand-alone Mode

  Sometimes it may be necessary to use Synchronize while disconnected from the network (for example if you carry your laptop computer with you when traveling). Stand-alone mode allows you to do this. Stand-alone capability can be enabled via the configuration/preferences dialog for each client. When running in stand-alone mode, the client accesses a local copy of the user's data that is stored on the local hard disk. When the user reconnects to the server, any changes made while running in stand-alone mode are merged with the server database (at the discretion of the user).

  Stand-alone mode is functionally equivalent to client-server mode with the following exceptions:

  • Database information for other users is not accessible, since only the original user's calendar is stored on the local disk.
  • Only calendar items falling within the range of one month in the past and 3 months in the future are saved locally.
  • When merging calendar items created in stand-alone mode with the server, only items falling within the range of one year in the past and 3 years in the future are merged.
  • One cannot open a schedule or become agent for another user.
  • One cannot schedule new items for users in remote databases
  • One cannot set/modify calendar permissions.

  When stand-alone mode is enabled, the user is prompted to save his or her data to the local disk each time he or she exits Synchronize. Upon subsequent restart, Windows users can click the "Stand-alone" check box in the login dialog. UNIX/Motif users will be automatically prompted to run in stand-alone mode when connection to the server fails.

  Time Zone Settings

  Since Synchronize will be keeping users’ appointments, an important requirement for trouble-free Synchronize use is to have the proper time zone setting in place with consistent rules for transitions into and out of daylight savings time for all users. This is especially true if users are located in different time zones. Users with differing time zone settings or inconsistent transition rules may not always see appointments displayed at the correct times on their calendars. Any inconsistencies must be addressed before users are able to use Synchronize reliably. To ensure consistent behavior, you must first make sure that all users who are scheduling within the same time zone have the same time zone configuration setting. For Windows users, this must be set in the configuration options/preferences window (also see below for instructions on setting default configuration options). For UNIX users, the TZ environment variable is used to specify the time zone. If necessary, this variable can be set by uncommenting and editing the following line in the bin/synchronize.sh client startup script:

  TZ=timezone; export TZ

  You must substitute your correct time zone (e.g., PST8PDT) in place of timezone above. Although users’ time zone settings may be set consistently, it cannot always be assumed that daylight savings transitions are handled correctly (especially when running clients for multiple platforms in non-U.S. time zones). A convenient mechanism for keeping all Synchronize users running with the same daylight savings transition rules is by using the db/database/tztab file. Instructions for editing the file are included in the file. When this file is present on the server, clients attempt to match the value of their time zone setting to the corresponding entry in the file. If a match is found, the daylight savings transition rules corresponding to that entry in the file are followed. It is important to not change the rules once events have been scheduled. If events are scheduled under one set of transition rules and then those rules are changed later, the previously scheduled events may not appear at their correct times.

  Setting Default Configuration Options

  When users run Synchronize for the first time, it may be preferable to start them off with a pre-configured set of default options. This is especially true for a setting such as their time zone, since an incorrect time zone setting can cause meetings to be displayed at incorrect times (see Time Zone Settings above). Each client has its own way of handling default configuration options. Details for each are outlined as follows:

  Windows

  When the Windows client is started, it first looks in the Windows directory for a file called SYNCHRO.INI (typically C:\WINDOWS\SYNCHRO.INI) for its configuration options. If this file is not found, then Synchronize copies the SYNCHRO.INI file from the working directory (typically C:\SYNCHRO\CLIENT\SYNCHRO.INI) into the Windows directory for subsequent use. Behavior is unpredictable if no SYNCHRO.INI file can be found. An administrator need only provide the SYNCHRO.INI file in the working directory to initialize settings for first-time users. Any subsequent modifications to configuration options by the user are stored in the user’s SYNCHRO.INI file in the Windows directory.

  UNIX/Motif

  When the Motif client is first started, it typically looks for its X resource file installed as /usr/lib/X11/app-defaults/Synchronize. By default, the UNIX installation procedure will have created a symbolic link with the above name pointing to the resources/Synchronize X resource file in the Synchronize hierarchy. An administrator need only edit this file to initialize settings for first-time users. Any subsequent modifications to configuration options by the user are stored in the user’s home directory in the .synchronize directory. If a user’s Synchronize calendar appears blue with boxes around all the dates, this indicates that the Synchronize X resource file is not accessible by that client. If this is the case, you should check that the above mentioned X resource file exists (or a valid link to it exists) and is readable. If the file already exists and is correct, then you should check to see that any environment variables in that user’s environment are not causing the problem. Typical things to check for in the environment might be XAPPLRESDIR, XENVIRONMENT, XFILESEARCHPATH, XUSERFILESEARCHPATH, etc.

  Setting Default Calendar Permissions

  By default, users only have permission to schedule each other. If it is necessary to establish some alternative default calendar permissions (e.g., all users must be able to view others’ calendars, too), the file db/database/dat.perm can be edited to accomplish this. When the file is modified, the Synchronize server will detect the change to the file and update permissions appropriately. You may also edit the file while the Synchronize server is not running.

  To set the default permissions on users’ calendars, the administrator can add a special entry of the following format at the beginning of the file:

  #O <tab> __ALL__
  #J <tab> database_name
  #R <tab> names
  #C <tab> names
  #Y <tab> names
  #N <tab> names

  #J <tab> database_name
  #R <tab> names
  #C <tab> names
  #Y <tab> names
  #N <tab> names
  
  .
  .
  .
  
  #J <tab> database_name
  #R <tab> names
  #C <tab> names
  #Y <tab> names
  #N <tab> names

  A single <tab> must separate the field identifier (e.g., #O) from its value, and a blank line separates each #J section from the next. The #J designations are only needed if specifying access for users in remote databases. For the entry, the various items are defined as follows:

  • The #O field is required and must specify the value __ALL__ (two underbars before and after).
  • The #J field is required only if you are setting default permissions that apply to users from remote databases accessing local users’ calendars. The database_name is from the first field of the db/domains file and indicates for which database the following permissions apply. If setting permissions for multiple databases, then there must be a #J field for each database followed by one or more of the #R, #C, #Y, #N fields. See below for examples.
  • names is a comma-separated list of Synchronize names as defined in the first field of the db/users file. See below for examples.
  • The #R field is optional and indicates who will have read permission for users’ calendars. A value of __ALL__ indicates that all users can read others’ calendars by default.
  • The #C field is optional and indicates who will have write permission for users’ calendars. A value of __ALL__ indicates that all users can write to others’ calendars by default.
  • The #Y field is optional and indicates who will have agency permission for users’ calendars. A value of __ALL__ indicates that all users have agency status for others’ calendars by default.
  • The #N field is optional and indicates who will have scheduler permission for users’ calendars. A value of __ALL__ indicates that all users can schedule others’ calendars by default.

  Any of the above fields can be omitted (except #O) if they are not needed. This special entry effectively sets the calendar permissions for users who have not done so already. If a user modifies his or her permissions settings, then the default will no longer apply to them.

  As an example, suppose that you wish all local users to be able to schedule each other as well as view each other's calendars by default. The only entry you would need to make is as follows:

  #O __ALL__
  #R __ALL__
  #N __ALL__

  As another example, suppose that in addition to the scenario above, there are also four managers (Bill, Mary, Joe and Barbara) in a remote database who must have agency permission by default for all users in the local database. The local database is named "xwind" and the remote database is named "mtnview" according to the first fields in the db/domains file. The entry you would make is as follows:

  #O __ALL__
  #J xwind
  #R __ALL__
  #N __ALL__

  #J mtnview
  #Y Bill,Mary,Joe,Barbara

  Keep in mind that a user can change their permissions and override the default so that none of the managers could then become their agent.

  Administrator-Imposed Options

  The Synchronize administrator may find it necessary to impose special system-wide options on clients’ behavior. This can be done by editing the file db/database/client.opts. The format of an option entry is the same as that described for the db/database/server/server.opts file, i.e.,

  option: value

  The following options are supported in the 2.0.0 release or higher of the Synchronize client for UNIX/Motif and Windows.

  limitRecurring

  (True or False) When set to True, users are limited in the range of time for which a recurring item can be scheduled. Limits are as follows:

  Daily and Work-daily: 2-year limit
  Weekly and Biweekly: 10-year limit
  Monthly and greater: no limit

  The default value is False.

  requirePassword

  (True or False) When set to True, UNIX/Motif users without a Synchronize password are not allowed to log in. This is already the case with Windows clients. The default value is False.

  checkTime

  The number of seconds after which an idle client will automatically connect to the server and check for new calendar items. The corresponding client option is Database check interval. When too many users set their Database check interval values too low, it can cause performance problems. This option allows the administrator to override user settings.

  
  

  ---

  Server Administration

  Starting/Stopping the Synchronize Server for UNIX

  There are two ways you can start/stop the Synchronize server daemon (synchrod).

  1. CrossWind provides a convenient script (bin/synchrod.sh) for starting the Synchronize server. This script must be edited (using vi or some other text editor) before use and provides an easy way to ensure that the server is running at all times. It also notifies the Synchronize administrator if any problems occur. Because the script runs in the foreground, when executed from another script (e.g., a system rc startup script), it should be backgrounded, e.g.,

     bin/synchrod.sh &

     To stop the Synchronize server in this case, use the following steps:

     1. Determine the process ID (PID) and the parent process ID (PPID) of the synchrod process using a UNIX utility such as ps. When run from the startup script, the process listing for the synchrod should show "synchrod -noFork" in the command name field.
     2. Send a default kill signal (SIGTERM) to the parent process first and then to the process itself in that order, i.e.,

        kill PPID
        kill PID

     A useful side effect of using the bin/synchrod.sh startup script is that if you only kill the synchrod process (and not the parent script) in the example above, then the synchrod will be automatically restarted by the script. You should not use kill -9 (SIGKILL) to stop the synchrod. Doing so may cause you to lose data as it will not be able to write unsaved data to disk.

  2. Start the Synchronize server by executing the server binary directly. For example, use the command:

     platform/bin/synchrod

     where platform is the platform-specific directory corresponding to the machine on which it runs. When the server is run in this fashion, there is no need to background it as above since it runs as a daemon and automatically backgrounds itself. Executing the server binary directly makes it easier to use special command-line options such as -filterDups without having to edit the startup script. CrossWind recommends that you use the synchrod.sh startup script under normal circumstances.

     To stop the Synchronize server in this case, follow these steps:

     1. Determine the process ID (PID) of the synchrod process using a UNIX utility such as ps.

     2. Send a default kill signal (SIGTERM) to the process, e.g.,

        kill PID

     You should not use kill -9 (SIGKILL) to stop the synchrod. Doing so may cause you to lose data as it will not be able to write unsaved data to disk.

  Starting/Stopping the Synchronize Server for Windows NT

  The Synchronize server for Windows NT runs as an NT service. Starting and stopping it is performed via the Services icon in the Control Panel as with any NT service. You may also start and stop it from the command-line using the following syntax:

  net {start|stop} synchrod

  If the Synchronize server for Windows NT is unable to start for some reason and its log file (db\database\server\server.log) is not accessible, then it will attempt to write a log file called synchrod.log into the directory that contains the synchrod.exe binary.

  Server Options and Details

  Overview

  The Synchronize server has several configurable options and command-line options that control its behavior. The file containing the options settings is db/database/server/server.opts. This file should be edited by the Synchronize administrator when server behavior must be adjusted from that of the defaults. Most of these options are common to both UNIX and Windows NT servers. Exceptions are noted. By default, the Synchronize server listens on TCP port 3751. If communication through a firewall is necessary, then access to this port must be enabled before any client or other process will be able to communicate with the server.

  Options File Settings

  All configurable options are shown below with their default settings. The format for an option entry is:

  option:  value

  Comments can be entered with a "#" or a "!" as the first character of the line. This file can be updated while the server is running, as the server checks periodically (see checkInterval) to see if the file exists and if it has been changed. The following options are listed alphabetically:

  checkInterval

  The time (in seconds) between checks of various files. The files checked are as follows:

  • The db/users file
  • The db/domains file
  • The db/groups hierarchy
  • The db/database/server/server.opts file

  The default value is 900 (15 minutes). If you wish to see changes to the above files take effect immediately, you can send the UNIX Synchronize server a kill -1 (SIGHUP) signal. You must restart the Windows NT Synchronize server to effect changes immediately.

  debugLevel

  A number designating how much information is logged to the db/database/server/server.log file. The default value is 0.

  • 0 - only fatal errors are logged
  • 1 - information about network connections is logged
  • 2 - disk I/O activity is logged
  • 3 - reserved
  • 4 - reserved
  • 5 - detailed database activity logged

  inetRange

  A comma-delimited list of IP addresses from which the server will accept connections. One example of a valid inetRange is as follows:

  201.93.140.*,201.93.145-147.*,201.94.133.24

  You can use the inetRange option to prevent unauthorized clients from accessing your server. If no value is specified, the server will accept connections from any IP address.

  mailerCmd

  (UNIX only) The command used by the server to deliver e-mail on behalf of clients. The default value is /usr/lib/sendmail.

  mailerDelimiter

  (UNIX only) A character string used to separate e-mail recipient list addresses. The default value is a space. If your messaging system complains about an invalid addressee list, you might try specifying a comma here instead.

  mailerHost

  (Windows NT only) Name of the host to which Synchronize should connect via SMTP when sending e-mail on behalf of clients. SMTP is used by default to send e-mail. If a recipient address (as defined in the 3rd field of the db/users file) is prefixed with "MAPI:" then e-mail to that address is sent via the MAPI mail system, not SMTP. The default value is localhost.

  mailerOpts

  (UNIX only) The command-line option(s) used by the mailerCmd. The default value is -t.

  maxClientThreads

  The maximum number of client reader threads to service client requests. The value of maxClientThreads is automatically limited to at most maxSockets-1 (see -maxSockets in the Command-line Options for UNIX section below). This option is only available with the multi-threaded server. If set to zero (UNIX only), multiple threads are disabled and the server runs as a single-threaded process. The minimum number of client reader threads allowed for Windows NT is 1 (even if the option is set to 0). The default value is 20. In most cases, the default value will be sufficient and CrossWind does not recommend that it be changed.

  maxMsgLen

  The maximum network buffer size (in bytes). A larger number can improve performance in some circumstances, but the default will be sufficient in most cases. The default value is 8192.

  remoteDbUpdateInterval

  The time (in seconds) between checks of remote databases for changes to their users files. The default value is 14400 (4 hours).

  threadTimeout

  The amount of time (in seconds) after which a hung thread is automatically killed. This option only applies to the multi-threaded server. This option prevents a hung thread from living indefinitely. The default value is 1800 (30 minutes).

  truncateLog

  (True or False) When set to True, the contents of the server.log file (if any) from a previous instance of the synchrod will be removed before new information is logged. When set to False, each time the server is restarted, it will append to the existing log file. The default value is True.

  writeDelay

  The amount of time (in seconds) between writes to disk of modified data. If non-zero, database modifications are cached during the delay period and flushed to disk at the end of the period. If set to zero, any modifications to the database are immediately written to disk. The