SYNCHRONIZE
    System Administrator’s Guide

    Version 2.0

    CrossWind Technologies, LLC.


    © 1993-1997 CrossWind Technologies, LLC.
    Part Number 5201000-009
    Synchronize is a trademark of CrossWind Technologies, LLC.
    Motif is a trademark of the Open Software Foundation, Inc.
    PostScript is a registered trademark of Adobe Systems, Inc.
    UNIX is a registered trademark of UNIX Systems Laboratories, Inc.
    X Window System and X are trademarks of the Massachusetts Institute of Technology.
    Microsoft, MS, DOS, Windows and Windows NT are either trademarks or registered trademarks of Microsoft Corporation.
    All other brand and product names are either trademarks or registered trademarks of their respective companies.


    Table of Contents


    INTRODUCTION

      How to Contract CrossWind

      Supported Server Platforms

      Supported Desktop Clients

      System Requirements

    INSTALLING SYNCHRONIZE

      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 SynchronizeTM 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 default value is 900 (15 minutes).

          Command Line Options for UNIX

          The Synchronize server for UNIX accepts the following command-line options:

          -filterDups

          Causes the Synchronize server to search for duplicate items, then filter and discard them. This option is useful when duplicate Synchronize database files are concatenated together (as might be the case in a partial backup). After completion, the Synchronize server will exit and you must restart it in its normal mode of operation.

          -maxSockets N

          Sets the maximum number of simultaneous network connections (open file descriptors) that the server can maintain. Upon startup the Synchronize server will automatically determine the maximum number that the system will allow and log the value in the server log file. The actual limit will be either the command-line option setting, 255 or the system limit determined at startup, whichever is smallest. The default value is system dependent.

          -newLicense license

          Applies the specified license to the database.

          -noFork

          Causes the synchrod to run in the foreground.

          -showLicense

          Displays the license information for the database.

          -socketOffset N

          The synchrod will listen at an offset of N from the default TCP port of 3751. N must be a non-negative number. This option can be used when running multiple Synchronize servers on the same machine. When a server is running at an offset of N, then clients can connect to it by specifying hostname:N as the server.

          -test

          Causes the synchrod to run in the foreground and send all log output to stdout rather than db/database/server/server.log
          .

          -version

          Reports the version and platform to stdout.

          Server Details

          One server process is started to serve all Synchronize clients for a particular database. There is great advantage in preventing any other process from directly accessing the database files:

          • The server’s read cache will never become stale so reads from disk are greatly reduced.
          • An optional delayed-write feature can be used by the server (see the writeDelay option).

          The limitation on the number of open file descriptors per process necessitates that the server close the socket connections for old clients in order to accept new ones when the number of simultaneous clients approaches the limit (see the -maxSockets option in the Command Line Options section for more details on this limit). This results in the server dropping the connection to a client. However, a reconnection strategy allows those clients to reconnect automatically with the server at their next request. Since typically at least 60 file descriptors are available and the reconnection delay is about 1 or 2 seconds, this strategy should result only in a slight delay in accessing the server for clients whose connections have been dropped. In addition, a positive side effect of this strategy is that the server may be killed and restarted without adversely affecting existing clients.

          The Synchronize server sends its output to a log file in the db/database/server directory called server.log. See the debugLevel option for information on how to control the amount of information logged.

          Multi-threaded Server Details

          Synchronize incorporates a multi-threaded server for Windows NT and several UNIX platforms. The multi-threaded design optimizes performance by alleviating bottlenecks associated with disk and network I/O. The server includes a flexible design to support both multi-threaded and single-threaded process architectures.

          One administrator-configurable option exists and four classes of threads are supported (not counting the main thread, which directs the activity of the other threads). The four classes of threads are as follows:

          • Client reader threads: Threads to service network client requests. Use of multiple threads here ensures that network bottlenecks to some clients do not degrade performance for others. The maximum number of client reader threads is configurable with the maxClientThreads option in the file db/database/server/server.opts.
          • Single write flush thread: Handles writes to the disk. While this thread is busy, any client reader thread can provide services for read and write requests, as long as the write flush thread is not operating on that portion of the data on which a write request operates. In a single threaded process environment, disk I/O can cause performance bottlenecks despite the delayed write feature.
          • Single server-to-server communication thread: Individual servers need to get state information, such as the current list of users, from other servers so that they can provide that state to their local clients. This thread performs that function, but, again, network bottlenecks (or remote server bottlenecks) will not affect performance for local clients.
          • Single router thread: This thread manages the forwarding agent (router) which is described in the section The Forwarding Agent.


          Setting Up Multiple Synchronize Databases

          Overview

          Synchronize uses a central database containing calendaring information for the users it serves. As the number of users grows, the size of and traffic to the database grows in a corresponding fashion. Eventually, the database may be so large as to cause a performance bottleneck. For example, while support for 500 to 1,000 users in a single database may be feasible, support for 5,000 users is not. To deal with such issues of scale, as well as administration requirements within an organization, the Synchronize 2.0 release supports multiple distributed databases. Multiple Synchronize databases can exist on different hosts or on the same host. (See the Hosting Multiple Databases on the Same Machine section for more information on that topic.)

          Typically a group, department or site might have its own Synchronize server and database installed on a machine at that location while other groups, departments or sites might have their Synchronize servers and databases installed on machines over which they have control. It is also possible to have more than one Synchronize server and database on the same machine (see below). Whether you are setting up multiple Synchronize servers and databases for the first time or joining a group of existing ones, the following instructions will help you.

          You inform a Synchronize server of the presence of remote databases by editing the db/domains file. The file consists of two or more entries identifying the local and remote database(s) in the following format:

               database_identifier, hostname, database_alias

          Definitions of the above three fields are as follows:

          database_identifier

          A string uniquely identifying the database. It is the identifier by which other sites associate an event with a particular database. The database_identifier must be unique between all databases that know about each other, and must never change.

          hostname

          The name of the machine on which the server for that database runs. If you move your database from one host to another, then Synchronize administrators for remote databases must change this field in their db/domains files to reflect that move. If multiple Synchronize databases exist on a single host, then the hostname:N notation can be used to specify them as needed.

          database_alias

          This field is optional and contains a string identifying the remote database name as presented to users. If the database_alias is not specified, then the name presented to users is that of the database_identifier. Use of the third field is encouraged so that the user sees meaningful database names. This field can be changed at any time if necessary.

          An example of a domains file is as follows:

            sc, whirlwind, Santa Cruz
            mtnview, lupine, Mountain View
            cupertino, hpuxsv8, Cupertino

          The above example assumes that there is a database on a machine called "whirlwind" in the city of Santa Cruz, another on a machine called "lupine" in the city of Mountain View, and a third on a machine called "hpuxsv8" in the city of Cupertino. The same unedited domains file can be shared among all Synchronize databases thereby minimizing administration effort.

          Note that communication among Synchronize databases must be bilateral. For instance, in the example above, Cupertino must have an entry in its db/domains file for Santa Cruz if Santa Cruz has an entry for Cupertino. Behavior is unpredictable if this rule is not met.

          The Forwarding Agent

          When a user schedules or modifies a calendar item that includes invitees in remote databases, those changes are first made in the local database. It is at this time that the Synchronize forwarding agent comes into play. The agent spends most of its time sleeping, waking up only to query its local Synchronize server for new or modified calendar items that need to be forwarded to remote databases. If any such items do exist, the agent attempts to do so. If for some reason the agent fails to forward items to a particular remote database (e.g., the remote machine is down for maintenance), then the agent will try again when it next wakes up. The forwarding agent for your local database is only responsible for forwarding information from the local database to remote databases, i.e., it never retrieves information from them. Your local database receives information sent from remote databases by the forwarding agents running on those remote servers.

          Behavior of the forwarding agent is controlled by options in the file db/database/server/router.opts. Comments are marked with a "#" or a "!" as the first character in a line. This file can be updated dynamically by the Synchronize administrator as the forwarding agent checks periodically (see checkInterval) to see if the file exists and if it has been changed. The available options are defined as follows:

          checkInterval

          The time (in seconds) that the forwarding agent sleeps between attempts to forward information to remote databases. The default value is 1800 (30 minutes). Too low a value for a very large database can diminish performance for users.

          debugLevel

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

          0 - only fatal errors are logged
          1 - information about network connections is logged
          2 - summary of forwarding activity is logged
          3 - detailed forwarding activity is logged

          forwardRange

          The number of months that the agent will go forward in time from the current day to look for events to forward. For example, if set to 6, an event scheduled one year from now will not appear in remote users’ calendars until that date falls within a six-month window from the current date. A value of 6 is the default.

          backwardRange

          The number of months that the agent will go backward in time from the current day to look for events to forward. A value of 1 (one month) is the default.

          Starting and Stopping the Forwarding Agent

          The forwarding agent (sync.forward) binary is located in the platform/bin sub-directory in the Synchronize hierarchy. Previous versions of Synchronize required that the administrator start and stop the forwarding agent manually. The Synchronize 2.0 forwarding agent is automatically maintained by the Synchronize server and no interaction by the administrator is needed. In the case of the multi-threaded server, the forwarding agent runs internally to the server as a thread. In the case of the non-multi-threaded server (or a multi-threaded server for which threads have been disabled), the sync.forward is forked as a separate external process but is still automatically maintained by the server. Behavior of the agent can be adjusted with the options as specified above.

          Groups Spanning Databases

          As Synchronize databases are linked together in order for users within large organizations to schedule each other using Synchronize, it becomes necessary to make access to users in remote databases as seamless as possible. One way that an administrator can facilitate such access is to create groups that include users both from remote databases as well as the local one. The format of an entry in a group file for a remote user is as follows:

               user@database

          where user reflects either the remote user’s Synchronize_name or Synchronize_alias in the db/users file for the remote database, and database reflects either the database_identifier or database_alias in the db/domains file for the remote database. The "@" designation for users in the local database is optional.

          For example, using the sample domains file mentioned previously, if a Strategic Marketing group spans two databases, where the local database is has a database_identifier of "sc" and the remote database has a database_identifier of "mtnview," the Strategic_Marketing group file may contain the following entries:

            Joe@Santa Cruz
            Tom@Mountain View
            Larry@Santa Cruz
            Rhonda@Santa Cruz
            Shirley@Mountain View
            Jack@Mountain View

          Although the "@Santa Cruz" designation is not strictly necessary for the local user entries, it allows the exact same group file to be used in both the "Santa Cruz" and "Mountain View" databases. This allows Synchronize administrators to share the work they have done. Note that the user specified in a group file will always refer to a matching Synchronize_alias before a matching Synchronize_name. In the same fashion the database specified after the "@" symbol in a group file will always refer to a matching database_alias before a matching database_identifier.

          The Windows client does not support groups which span databases. It simply ignores any entries using the "@" designation.

          Hosting Multiple Databases on the Same Machine (UNIX Only)

          In some cases, it may be necessary or desirable to have the same machine host multiple Synchronize databases/servers. For example, if you only have one machine available to you, yet must host more users than a single Synchronize server may be able to handle, then splitting those users among multiple databases on the same system might solve that problem. If you are planning in the future to expand your Synchronize user population in various departments or groups, then you may find it desirable to give each department or group its own database. Moving an existing database to another machine in the future is a very simple procedure, whereas splitting a single database into two or more when it has grown too big is more involved. Only the UNIX Synchronize server can be installed this way. The Windows NT Synchronize server does not support this capability. There are some important points to keep in mind when hosting more than one Synchronize database on the same machine:

          • There must be a separate directory hierarchy for each Synchronize database on that machine and you must start a Synchronize server (synchrod) for each database. Each synchrod must have its own value of the SYNCHROPATH environment variable so that it knows where to find its corresponding database.
          • Each synchrod process must listen on a different TCP port. You can specify a port other than the default (3751) by using the -socketOffset command-line option (see Server Options and Details).
          • When a client or agent tries to connect to a Synchronize server running at an offset from the default port, the hostname:N notation must be used to specify the server name. For example, the command "synchronize -server whirlwind:2" specifies that the client should connect to the Synchronize server running on whirlwind at an offset of 2 (TCP port 3753). The SYNCHROSERVER environment variable could also be used.

          As an example, assume that a single machine will host three Synchronize databases. The databases will serve the Sales, Marketing and Manufacturing departments. First, you must create three directories, one for each database. For example,

            /usr/local/lib/synchronize-sales
            /usr/local/lib/synchronize-mktg
            /usr/local/lib/synchronize-mfg

          After installing the Synchronize server software in each location and setting up Synchronize user accounts in each, you must edit the db/domains file for each. Let’s assume that the host’s name is "soapstone". The db/domains file for each might be as follows:

            Sales, soapstone (could also be soapstone:0)
            Marketing, soapstone:1
            Manufacturing, soapstone:2

          To start the three servers, you might have a master script executed at boot time such as:

            #!/bin/sh
            /usr/local/lib/synchronize-sales/bin/synchrod.sh &
            /usr/local/lib/synchronize-mktg/bin/synchrod.sh &
            /usr/local/lib/synchronize-mfg/bin/synchrod.sh &

          Each synchrod.sh script above sets the appropriate value of SYNCHROPATH and specifies the appropriate socketOffset option using the OPTIONS variable provided in the script. For example, the synchrod.sh corresponding to the Marketing department would contain the following settings:

            SYNCHROPATH="/usr/local/lib/synchronize-mktg"
            export SYNCHROPATH
            OPTIONS="-socketOffset 1"

          Limitations

          The following limitation applies to all supported platforms when using multiple databases:

          • When a user in a remote database attaches a popup note to a calendar item visible to a user in the local database, then the user in the local database does not see that calendar item become bold nor is the optional popupnote indicator (*) displayed if only remote popup notes are attached.

          The following limitation applies only to the Windows client when using multiple databases:

          • Groups spanning databases are not implemented. It simply ignores any entries using the "@" designation.

          E-Mail Administration

          Overview

          Synchronize supports e-mail notification to users about scheduled events. Synchronize accomplishes e-mail notification in a variety of ways. E-mail can be sent by clients or servers depending on the platform and configured options. For Windows clients, e-mail is always sent by the Synchronize server for them. For UNIX/Motif clients, the server can optionally send the e-mail, but the default is for the client to send the mail itself using sendmail.

          Client E-Mail Options

          The following options can be set in the Configuration/Preferences dialog for each client:

          • Receive mail about events - (True/False) If True, you are notified by e-mail when someone schedules you for an event. You also receive e-mail notification for certain modifications and deletions. The default value is False.
          • Send mail to event originator - (True/False) If True, you will receive e-mail notification when you schedule an event. The default value is False.
          • Enable sending mail - (True/False) (Windows only) If False, all e-mail originating from this user is disabled. The default value is True.
          • Mail command - (UNIX/Motif only) The command used by Synchronize to deliver mail. The default value is /usr/lib/sendmail.
          • Mail delimiter - (UNIX/Motif only) A character string used to separate e-mail recipient list addresses. The default value is a space. Another typical value for this option might be a comma.
          • Mail options - (UNIX/Motif only) The command-line option(s) used by the Mail command. The default value is -t.

          The following option(s) apply only to the UNIX/Motif client and can be added to the client’s X resources (e.g., the resources/Synchronize file):

          • serverSendmail - (True/False) If True, the Synchronize server will deliver mail on behalf of the client. The default value is False. The format of the X resource entry would be as follows:

            Synchronize*serverSendmail: True

          Server E-Mail Options

          The following e-mail related options can be set in the db/database/server/server.opts file on the server. See the Server Options and Details section for more details about these options:

          • mailerCmd
          • mailerDelimiter
          • mailerHost
          • mailerOpts

          UNIX Sendmail and Trusted Users

          A sendmail trusted user is one who is allowed to use the -f command-line option to specify the sender of the message. The UNIX Synchronize server attempts to use the -f option when sending e-mail on behalf of clients so that the correct Synchronize user appears as the sender of the message. If the owner of the Synchronize server is not a trusted user, then sendmail ignores the attempt. In the case of e-mail sent by a UNIX Synchronize client, the -f flag is not attempted since the sender address defaults to the user's UNIX ID anyway.

          Trusted users are defined in the sendmail configuration file (sendmail.cf) by the T configuration command. The T command must begin a line. One or more space-delimited user names then follow on that same line. There may be multiple T commands in a sendmail.cf file, each adding names to the list of trusted users.

            T uucp
            Troot daemon

          The above T commands show that there may optionally be white space between the T and the first name in any list of names. They indicate that uucp, root, and daemon are trusted, and have been added to the list of trusted users in that order. Depending on your version of sendmail, you may need to "freeze" the configuration file so modifications to the sendmail configuration are recognized. To do this, invoke sendmail with the -bz command-line option (e.g., /usr/lib/sendmail -bz). If frozen configuration files are not supported with your version of sendmail, you will probably see an error message indicating this. In this case, the error message can be safely ignored.

          If the Synchronize server is sending e-mail where the sender address appears to be that of the Synchronize database owner (e.g., bin), then there are two options to make e-mail appear as it is from the correct Synchronize user:

          • Change the Synchronize database owner to that of an existing trusted user. To do this, follow these steps.

            1. Make sure that the Synchronize server (synchrod) is not running.
            2. Do a recursive chown to the new owner in the Synchronize directory
              (e.g.,
              chown -R daemon /usr/local/lib/synchronize). Keep in mind that the Synchronize database cannot be owned by root.
            3. Restart the Synchronize server.

          • Add the current Synchronize database owner to the list of trusted users.

          Customizing E-Mail Notification

          The Synchronize administrator may pre-define the format and content of the e-mail messages that notify users of events. The file db/database/mailmsg can be edited with a text editor according to the following formatting rules:

          1. The file db/database/mailmsg contains up to six separate templates. Each template is separated from the next by at least one blank line.

          2. A template consists of two parts, a template_header and template_body, of the following format:

                 template_header:
                 template_body

            A template_header followed by a colon (":") occupies the first line of the template and the template_body occupies the second and subsequent lines up to the next blank line.

          3. Valid values for a template_header are listed and described as follows:

            NewEventSubject         - Message subject for new events
            NewEventBody
                          - Message body for new events
            ModifyEventSubject
                - Message subject for modified events
            ModifyEventBody
                    - Message body for modified events
            DeleteEventSubject
                - Message subject for deleted events
            DeleteEventBody
                      - Message body for deleted events

          4. When included in a template_body, the following macros are expanded as noted before the e-mail message is sent:

              %t - event title
              %o
              - event originator
              %s
              - event start time/date
              %e
              - event end time/date
              %i
              - event invitees
              %r
              - event readers
              %w
              - event writers
              %p
              - popup notes (first 3 KB of each)
              %%
              - the % symbol itself

          5. To specify a blank line in an e-mail message, the template_body can contain a backslash ("\") on a line by itself.

          An example of a db/database/mailmsg file containing two templates is as follows:

          NewEventSubject:
          New event "%t" scheduled by %o

          NewEventBody:
          The following event:
          \
          "%t"
          \
          has been scheduled by "%o" to begin at %s
          and end at %e.


          Database Administration, Utilities and Procedures

          There are various tools available for performing the administrative tasks mentioned below on the Synchronize database. Tools for measuring performance as well as technical papers on other administrative topics such as the database file format are also available. These can be found on CrossWind’s FTP server in the following locations:

          http://www.crosswind.com/products/synchronize/admintools
          http://www.crosswind.com/products/synchronize/docs/techpapers

          See the README files in corresponding directories for descriptions of directory contents.

          Backing Up the Database

          CrossWind recommends that you back up your Synchronize database on a daily basis. Only the db subdirectory and its contents need to be backed up. Utilities such as tar or cpio are recommended and easy to use for this task under UNIX. Under Windows NT, any backup software can be used including the built-in system backup facility. Whichever tool you decide to use, make sure that it saves all files and directories including empty directories and zero-length files. As an example, if you have a special UNIX disk partition or file system called /backups from which the nightly backups are made, then you might execute the following script each night:

          #!/bin/sh

          BACKUP_DIR="/backups"
          SYNC_DIR="/usr/local/lib/synchronize"

          cd $SYNC_DIR
          tar cf - db | compress > ${BACKUP_DIR}/db.tar.Z

          You do not need to stop the Synchronize server when backing up the database. When deciding what time the backup should occur, keep in mind that the Synchronize server propagates unfinished to-dos to the next day around midnight. The amount of time required to do this depends on the size of the database and the speed of your system. For this reason, when scheduling your backup, it’s probably a good idea to avoid the time between 12:00 a.m. and 1:00 a.m.

          Restoring the Database

          There are three scenarios to consider when restoring the Synchronize database:

          • A full restore, which will reset the state of the database to the time of the last backup.
          • A partial restore of particular database files when data for only a particular range of time (e.g., "this week" or "last month") must be restored for all users.
          • Restoring a particular user’s data for an arbitrary range of time.

          When performing a full restore, you should carefully follow these steps:

          1. Stop the Synchronize server.
          2. Restore the db subdirectory and its contents from a previous backup into the appropriate location in the existing Synchronize hierarchy.
          3. Make sure that the ownership of the db subdirectory and its contents is the same as it was before the restore. You can use the chown -R command to ensure this.
          4. Restart the Synchronize server.

          When performing a partial restore, you should carefully follow these steps:

          1. Stop the Synchronize server.
          2. Restore the db subdirectory and its contents from a previous backup into a temporary location.
          3. Use the http://www.crosswind.com/products/synchronize/docs/techpapers/calendar.txt document on CrossWind’s FTP server to locate the files of interest in the database.
          4. You can either overwrite existing database files with files from your backup or you can merge them. Instructions for each are as follows:
            1. To overwrite your existing database files, simply copy the appropriate files from the temporary location into the existing Synchronize hierarchy.
            2. To merge your backup data with the existing data, first remove the header lines (the two lines beginning with #B and #F at the very beginning of each file) in each backup file you will be restoring. Once completed, concatenate each file from your backup onto its counterpart in your existing database.
          5. Make sure that the ownership and permissions of the restored files are consistent with what is already there. You can use the chown and chmod commands to ensure this.
          6. If you merged your database files as specified in step 4b) above, then you must start the Synchronize server with the -filterDups command-line option. After it has finished filtering duplicate events, it will exit automatically.
          7. Restart the Synchronize server as you normally would.

          When restoring data for a particular user or users, you should carefully follow these steps:

          1. Make sure that the user whose data is to be restored has a valid entry in the Synchronize users file. If you have just re-added the entry (for example if you improperly deleted it), you may need to wait as long as the value of the checkInterval server option as specified in the Server Options and Details section. See that section for more details.
          2. Restore the db subdirectory and its contents from a previous backup into a temporary directory (e.g., /tmp/synchronize) on the same UNIX system as your working database. If you host your Synchronize database on a Windows NT system, then you must install the Synchronize server software on either another Windows NT system or another UNIX system and perform a full restore to that auxiliary system.
          3. Start another Synchronize server for the temporary database. If it is running on the same UNIX host as your working database, then make sure you first set the SYNCHROPATH environment variable to the temporary directory before starting it. You must also use the -socketOffset N command-line option to avoid it conflicting with the default port on which the working Synchronize server is already listening. If your working database is installed under /usr/local/lib/synchronize, then you might type the following:

            setenv SYNCHROPATH /tmp/synchronize
            cd /usr/local/lib/synchronize

            platform
            /bin/synchrod -socketOffset 1

          4. Use the sy_mover utility provided by CrossWind Technologies to move the user's data from hostname:N to hostname, where hostname is the name of the machine on which the Synchronize servers are running. The :N notation references the offset (if any) that you specified in the previous step. If the temporary Synchronize server is running on a different machine than the working database, then specify the appropriate host names instead. Please see the instructions included with sy_mover for more details on its use.
          5. After the move has been completed, verify that the user’s data has been restored by having the user browse his or her calendar with a Synchronize client.
          6. After verification that the correct data is in place, stop the temporary Synchronize server and remove the temporary directory you created for it.

          Expiring Old Data from the Database

          As time passes, the size of your database will increase. Expiring old data periodically will conserve disk space as well as help to improve performance and decrease the virtual memory footprint of the Synchronize server. The sy_expire utility allows you to specify how much past data to keep and deletes everything older than the date you specify. There is no strict rule about how much data to keep around. Base your judgment on disk and virtual memory usage. CrossWind recommends that you make a backup of your database before expiring data. See the instructions that come with sy_expire for more information on its options.

          Moving the Database to Another Machine

          CrossWind recommends that you back up your database before moving it to another machine. See the Backing Up the Database section for more information.

          Moving from One UNIX System to Another

          The following procedure covers the cases where UNIX systems are both of the same type or of different types. For moving a database between a UNIX and Windows NT system, see the section Moving Between a UNIX and Windows NT System below.

          1. Create a directory on the new machine where Synchronize will be installed (e.g., /usr/local/lib/synchronize).
          2. Kill the Synchronize server daemon (synchrod) on the original machine.
          3. Use tar (or cpio) to copy the entire Synchronize hierarchy from the original machine to the new machine. You should verify that ownership and permissions are preserved. You may want to use chown -R to ensure this.
          4. If the new machine is of a different type than the original, extract the Synchronize distribution for the new platform into the existing hierarchy on the new machine.
          5. Run the INSTALL script on the new machine. If you extracted the distribution in step 4 above, then you will be taken through the entire installation. Otherwise, you will be whisked immediately to the end of the installation and prompted to set up the 3 symbolic links. In both cases, your existing Synchronize license will be used and you will not be prompted to enter it.
          6. You may need to edit the SYNCHROSERVER environment variable in your bin/synchronize.sh startup script(s) to reflect the new server hostname to which clients should connect.
          7. If your database is one in a group of distributed Synchronize databases, then the administrators for the other databases should modify their db/domains files to reflect the new hostname for your database. The hostname is specified in the second field for each entry in the domains file.
          8. Start the Synchronize server daemon (synchrod) on the new machine.
          9. Once everything is up and running on the new machine and you have made a backup of the database, delete the entire Synchronize hierarchy on the original machine.

          Moving Between a UNIX and Windows NT System

          When moving a Synchronize database to Windows NT from UNIX or vice versa, the database files must be converted. Specifically, the EOL character used by Windows NT and that used by UNIX are different and must be converted. This conversion must be done in order for standard DOS/Windows text editors to work correctly on editable UNIX files (and vice versa) and for the Synchronize server to function correctly. Carefully follow these steps. The file conversions must take place on a UNIX system on which Synchronize is supported.

          1. Make sure the Synchronize server is not running.

          2. Copy your db subdirectory to a temporary working directory. For example in UNIX you might type the following:

            mkdir /tmp/tempsync
            cd /usr/local/lib/synchronize
            tar cf - db | (cd /tmp/tempsync; tar xf - )

            You should ensure that empty directories and zero-length files (if any) are also copied.

          3. Obtain the convertdb tar image for your platform (e.g., convertdb.sunos.tar) located in the http://www.crosswind.com/products/synchronize/admintools/convertdb subdirectory on CrossWind’s FTP server and extract it into your temporary directory containing the db subdirectory you just moved there. The following files will be extracted:

            README - These instructions
            convertdb.sh -
            Main script
            convertfile.sh -
            Helper script
            sy_convertfile -
            Conversion program
            sy_convertfile.c -
            Source code for sy_convertfile

            Depending on who owns the Synchronize database and who does the conversion, you may need to modify the ownership of the files in the database. To be safe, you can either run the conversion as root, or use the chown -R or find command on the db subdirectory to change it to the appropriate owner.

          4. Run the following command if you will be converting from UNIX to Windows NT:

            ./convertdb.sh -2dos

            or if you are converting from Windows NT to UNIX, then type:

            ./convertdb.sh -2unix

            The conversion may take several minutes depending on the size of your database and speed of your system.

          5. Now that the conversion is done, you must move the converted database into place. If moving from UNIX to Windows NT, you should do the following:
            • Install the Synchronize Server software on the Windows NT host, then stop the Synchronize server service (if it's running) and replace the existing db subdirectory with your converted one. Restart the Synchronize server service.

            If moving from Windows NT to UNIX, you should do the following:

            • Create the new Synchronize directory on the UNIX host and move the converted db subdirectory there. Extract the Synchronize distribution tar image into that directory and run the INSTALL program. The installation will detect the existing database there. Follow the instructions and enter your license string when prompted. Restart the Synchronize server. You are done.

          Moving a User from One Database to Another

          The following procedure describes how to move one or more users’ data from one Synchronize database to another. CrossWind recommends that you make a backup of your database before proceeding.

          1. If you have not already done it, install the Synchronize server and database on the target machine and add the necessary Synchronize user account(s) for the user(s) being moved.
          2. If the two databases involved share information with each other or with other Synchronize servers via the distributed databases mechanism, make sure that you have set up the db/domains file and that multi-database functionality is working correctly before proceeding.
          3. Obtain the sy_mover utility and its instructions from the http://www.crosswind.com/products/synchronize/admintools/sy_mover subdirectory on CrossWind’s FTP server.
          4. Use the sy_mover utility to move each user from the source database to the target database. See the instructions for sy_mover for details on various options and restrictions. If you have many users to move, you could simply put the list of names into a file (for example, /tmp/myusers) and execute a script such as:

            #!/bin/sh
            for user in `cat /tmp/myusers`
            do
            sy_mover -from soapstone -to tetraploid -user "$user"
            done

            This script assumes that the list of users contains only the Synchronize_name for each. If you made a copy of the db/users file for this purpose, then you will either need to edit it so that only the Synchronize_name appears, or you will need to modify this script to accommodate the more complicated format.

          5. After you have verified that users’ data has been correctly transferred, remove their names from the db/users file in the source database.

          Splitting a Database into Two or More

          You will need to obtain the sy_mover utility for your specific platform from the http://www.crosswind.com/products/synchronize/admintools/sy_mover subdirectory on CrossWind's FTP server. Be sure to carefully read the instructions provided on how to use the utility. The sy_mover utility can be run on any available supported UNIX platform and not necessarily those hosting the databases involved.

          You should arrange to have the appropriate revised license strings before beginning this procedure. If necessary, CrossWind can supply you with a temporary license string. Please contact your Synchronize supplier or your CrossWind sales representative for this information.

          In summary, you will be performing the following tasks:

          • Creating one or more new databases
          • Moving the appropriate users from the original database to the new database(s) using the sy_mover utility
          • Deleting those users from the original database that you just moved

          Follow these detailed steps carefully to split up your database:

          1. Make a backup of the db subdirectory for the database that you will be splitting. See the section Backing Up the Database for details on how to do this.
          2. Install the Synchronize software on the machine(s) where the new Synchronize database(s) will exist. This will require a new license string.
          3. You will need to create the db/users file on the new database(s). This can be copied from the original database but should be modified. Typically, you might copy the original and just delete the names you do not want in the new file. Do not delete any names from the original database at this time!!
          4. You must create/modify the db/domains files on both original and new databases. These can be copied from the original database but must be modified. The db/domains files for both original and new databases must be modified to reflect the new relationships. See the section Setting Up Multiple Synchronize Databases in this guide for details on this topic. All other remote Synchronize administrators should update their db/domains files as well to reflect the new changes to your setup. Make sure that you do not modify the first field of the db/domains file for any of the existing databases. Only the new database will have a new first-field entry.
          5. Once the new database is set up according to the steps outlined above and the original's db/domains file has been modified, the synchrod(s) on the new database(s) should be started and the one on the original restarted.
          6. Verify that you can see both databases from both servers by running a Synchronize client connecting to each server and verifying that remote users are indeed visible from both ends.
          7. Follow the instructions in the section Moving a User from One Database to Another in this guide to move users from the original database into the new database(s).
          8. Remove from the original database's db/users file the names of those users who no longer reside on that database.
          9. Apply the revised license string to the original database.

          Combining Databases

          You will need to obtain the sy_mover utility for your specific platform from the http://www.crosswind.com/products/synchronize/admintools/sy_mover subdirectory on CrossWind's FTP server. Be sure to carefully read the instructions on how to use the utility. The sy_mover utility can be run on any available supported UNIX platform and not necessarily those hosting the databases involved.

          You must have the appropriate revised license strings before beginning this procedure. If necessary, CrossWind can supply you with a temporary license string. Please contact your Synchronize supplier or your CrossWind sales representative for this information.

          In summary, you will be performing the following tasks:

          • Increasing the number of licenses on the target Synchronize database and adding the new names
          • Moving users’ data into the combined database using the sy_mover utility
          • Deleting the old Synchronize databases

          Follow these detailed steps carefully to combine your databases:

          1. Make a backup of each database you will be combining. See the section Backing Up the Database for details on how to do this.
          2. Pick which of the existing databases will be the target and apply a new license for the increased number of users to the target database.
          3. Add all the appropriate user names to the db/users file in the target database and make sure all names are visible when viewed with a Synchronize client.
          4. Follow the instructions in the section Moving a User from One Database to Another in this guide to move users into the combined database.
          5. After you have verified that the databases have been combined successfully, remove the other Synchronize databases that are no longer required.

          Import/Export of Users’ Calendars

          Synchronize provides a built-in command-line import/export mechanism in the UNIX/Motif client. For details on this feature, see the document http://www.crosswind.com/products/synchronize/docs/techpapers/io.txt available on CrossWind’s FTP server. The import/export functionality is not available for the 2.0 release of the Windows client.


          Performance Tuning

          In most cases, Synchronize should allow quick access to your calendar. Occasional delays of one or two seconds are normal. As the number of active users increases, duration and frequency of delays may increase. Performance problems are caused by one or more "bottlenecks" in system resources. Examples of system resources include network bandwidth, CPU availability, hard disk I/O, etc. Unfortunately there is no easy answer to the question, "How many Synchronize users can this system handle?" In general, you should be able to host a database of several hundred users on a modern lower-end UNIX workstation running a multi-threaded Synchronize server. The following topics should help you determine the cause of performance problems should they arise. Some topics are relevant to any application, not just Synchronize and can be used to determine performance problems in general with your systems.

          Server Performance

          In most cases, performance problems experienced by users tend to be caused by bottlenecks on the server. When most or all users are experiencing similar performance problems, this is a strong indication that a server-side performance bottleneck exists. CrossWind Technologies provides a simple script (synccheck.sh) for gauging server response time. This script can be found in the http://www.crosswind.com/products/synchronize/admintools/performance subdirectory on CrossWind’s FTP server. Responses of less than 1 second are good; responses of 1-2 seconds are acceptable; consistent responses of 4 seconds or more point to a performance bottleneck. When performance problems are perceived, the following items represent potential causes in order of most common to least common.

          • Disk I/O bottleneck - For a single-threaded Synchronize server, by far the most common performance problem is caused by a bottleneck in writing database files to disk. A multi-threaded server uses an independent thread to perform writes and should not exhibit a problem in this area. Disk writes are performed periodically according to the value of writeDelay in db/database/server/server.opts. The more frequent the writes, the more frequent the possible delays are for users. By setting the debugLevel to 2 in server.opts and using the synccheck.sh script, you can look for correlations between delays and the "writing" messages in the server.log file. There are three possible remedies for this type of problem:
            1. Move the Synchronize database onto a machine that supports a multi-threaded Synchronize server.
            2. Increase the value of writeDelay. The default value is 900 seconds (15 minutes). Try increasing the value to 1800 or 3600. The more you increase this value, the less often the Synchronize server will flush its write cache. The drawback to this approach is that if the machine on which the Synchronize server crashes, you will lose data entered since the last write flush occurred. If you have increased the writeDelay to 3600 or higher and performance is still unacceptable, then you might consider option 3 below.
            3. Move the Synchronize database onto a faster system of the same type. Although the same bottleneck may exist, it should be less evident when delays are shorter.
            4. Split the database into two or more databases thereby decreasing the disk I/O load on each. See the Database Administration, Utilities and Procedures section for more information on this topic.
          • CPU bottleneck - A CPU bottleneck can occur if there are too many applications or too many users placing too big a burden on the processing capabilities of the system. You should use your system’s performance monitoring tools to determine if and which applications might be placing too large a processing load on your system. Once you have determined that the CPU is a bottleneck, the following actions can be taken:
            1. If there are other applications running on the system and they are placing a significant load on the system, then consider moving some of the load elsewhere. In other words, run some applications on some other machine so that the remaining applications have more CPU resources available to them.
            2. If the Synchronize server is the only application running on this system, then it may be necessary to move it to a faster system.
          • Excessive virtual memory paging - When there is too little physical memory installed on the system and the memory required by active applications (including Synchronize) exceeds what is available, the system may spend inordinate amounts of time swapping memory pages back and forth between physical and virtual memory. This situation is typically characterized by a low application load on the system, but a very high system disk I/O wait and/or paging rate. You should use your system’s performance monitoring tools to determine if this is the case. When you have determined that your system is spending too much effort paging at the expense of application performance, the following may help remedy the situation:
            1. If the Synchronize server’s memory image is large in comparison to physical memory, then you should consider trimming the size of the Synchronize database so that its image in memory is smaller. The sy_expire utility is designed to do this. It is available in the http://www.crosswind.com/products/synchronize/admintools/sy_expire subdirectory on CrossWind’s FTP server. You should always make a backup copy of your Synchronize database before removing data.
            2. Add additional physical memory to the system or move the Synchronize server to a system with more physical memory.
            3. If there are other applications whose memory requirements contribute to the lack of available physical memory, consider running one or more on some other system so that more memory is available to the remaining applications.
          • Limited simultaneous client connections - There is a maximum number of open files that a system allows an application, typically in the range of 49 to 255. Synchronize determines the number upon startup and reports it in the file db/database/server/server.log as the value of "maxSockets". This number represents the maximum number of simultaneous client connections the server may manage. When the actual number of Synchronize clients is greater the number of available sockets, the Synchronize server routinely drops older client connections to accept new ones. Whether or not a user’s client is physically connected to the Synchronize server is completely transparent to the user. When a user makes a request to the Synchronize server, they are automatically reconnected if they had been previously dropped. When the number of active Synchronize clients greatly outnumbers the available connections, then the Synchronize server may be spending a significant amount of time juggling these connections. A ratio of five clients to one available connection is probably satisfactory in most cases. If this ratio is substantially higher, then it may cause a problem depending on users’ activity. This behavior can be observed by excessive rates of "accepted connection" and "closing connection" messages in the file db/database/server/server.log. A constant rate of 2 or more connection changes per second over a large amount of time may indicate a problem. If a problem does exist, the following options can be used:
            1. If the maximum number of open files is less than 255, then you should increase it (up to a maximum of 255). The Synchronize server will not use more than 255 even if the system allows more. The way you set this system parameter is system-dependent, but is commonly a kernel parameter that is configurable through your system’s administration tools. You typically must reboot your system when making this type of change.
            2. If the maximum is already set to 255, then there is a good chance that the problem is not caused by a limit on connections, but rather some other bottleneck. See the rest of this section for other possible causes of performance problems.
          • Network problems - When the network is excessively congested or prone to failures, transactions between the Synchronize server and clients can be adversely affected. If you possess network monitoring tools, then they will probably come in handy if you suspect network problems. If you do not possess special network monitoring tools, it’s still possible to identify poor network performance. For example, copying a file (via NFS, FTP, etc.) of a known size to or from a Synchronize server machine to a Synchronize client machine can indicate a network problem when the copy takes an unusually long time to complete. Synchronize itself does not typically consume a significant amount of network bandwidth. The obvious solutions to these types of problems are:
            1. Move the Synchronize database onto a machine that supports a multi-threaded Synchronize server. The multi-threaded Synchronize server makes more efficient use of network resources than does the single threaded Synchronize server.
            2. Reduce network congestion.
            3. Correct/repair faulty network hardware/software.

          Client Performance

          Typically, perceived client performance problems are caused by performance problems on the server. This is especially true when Synchronize users across the board experience similar performance problems. If this is the case, start with the Server Performance section above. Nonetheless, client-side performance problems can exist. Each of the following items addresses a potential bottleneck for a client:

          • CPU bottleneck - A CPU bottleneck can occur if there are too many applications or too many users placing too big a burden on the processing capabilities of the system. You should use your system’s performance monitoring tools to determine if and which applications might be placing too large a processing load on your system. Once you have determined that the CPU is a bottleneck, the following actions can be taken:
            1. If there are other applications running on the system and they are placing a significant load on the system, then consider running fewer applications at once.
            2. If Synchronize is the only application running on this system, then it is not likely that it is the problem.
          • Network problems - see the Network problems section above under Server Performance.
          • Excessive virtual memory paging - When there is too little physical memory installed on the system and the memory required by active applications (including Synchronize) exceeds what is available, the system may spend inordinate amounts of time swapping virtual pages back and forth between physical and virtual memory. This situation is typically characterized by a low application load on the system, but a very high system disk I/O wait and/or paging rate. You should use your system’s performance monitoring tools to determine if this is the case. When you have determined that your system is spending too much effort paging at the expense of application performance, one of the following may help remedy the situation:
            1. Add additional physical memory to the system.
            2. Run fewer applications simultaneously.


          LICENSING

          The licensing mechanism in Synchronize is a static one. If you have an N-user license for your database, then the first N users in the db/users file will be able to use Synchronize. The N+1st user will get a complaint from Synchronize and the application will then exit. The Synchronize license is enabled at the time of first installation.

          The number of licensed users at a site may be upgraded at any time. Simply contact your Synchronize supplier or CrossWind Technologies. A new license can be faxed, e-mailed, or communicated to you over the phone. No re-installation of the software is necessary.

          Applying a License to a Windows NT Database

          The license for your database is contained in the Windows NT Registry. The license itself is an encrypted string located in the pre-defined HKEY_LOCAL_MACHINE\SOFTWARE\ under the following key:

          CrossWind Technologies\Synchronize Server\Current Version\

          To view or alter the license string, use the Windows NT Registry Editor. Select the key referenced above and edit the "License" value entry by double-clicking on it. A string editor dialog will appear with the current license number. Replace this string with the new one given to you by CrossWind Technologies or your Synchronize supplier. The license information is checked and updated periodically according to the value of checkInterval in the server.opts file (see the Server Options and Details section). If you wish to see the change immediately, you must restart the Synchronize server.

          Applying a License to a UNIX Database

          To apply a new license, change directories to the top of the Synchronize hierarchy on the same machine that hosts the Synchronize database and type the following command (note that you may need to first set the SYNCHROPATH environment variable to the top of the Synchronize hierarchy, e.g., /usr/local/lib/synchronize):

          platform/bin/synchrod -newLicense license_string

          where platform indicates the platform-specific directory for the type of system on which you are running. If you get the response "Success!", your new license has been installed correctly and is in effect immediately. If not, contact your Synchronize supplier or CrossWind Technologies.

          You can query the database to find the status of your license by typing the following command:

          synchronize -showLicense

          Synchronize will then display your unique license ID (not the license_string), the number of currently licensed users and the expiration date of the license, if applicable.