Installation Guide
CrossWind Technologies, Inc.
© 1993-1997 CrossWind Technologies, Inc.
Part Number 5201000-009
Synchronize and CyberScheduler are trademarks of CrossWind Technologies, Inc.
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.
Macintosh is a registered trademark of Apple Computer, Inc.
All other brand and product names are either trademarks or registered trademarks of their respective companies.
Table of Contents
INTRODUCTIONSynchronize
CyberScheduler Installation Guide
This guide describes the installation of the Synchronize server and CyberScheduler from CrossWind Technologies, Inc.
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 supports servers for Windows NT and over 20 UNIX platforms, as well as clients for the Web, Microsoft Windows, Macintosh, 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 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.
Synchronize 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.
Synchronize CyberScheduler is available for the following UNIX platforms:
Supported Browsers
Web browsers must support HTML version 2.0 or higher and JavaScript capability is recommended. There are no hardware requirements or other special requirements except as specified by the browser manufacturer.
Supported Web Servers
The web server which will host the Cyberscheduler Web server component must:
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. To use CyberScheduler, you must have both a Synchronize server and CyberScheduler software installed.
|
UNIX |
RAM |
Disk space |
Virtual memory |
Other requirements |
|
Synchronize Server for UNIX |
Minimum recommended by OS |
7-10 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. |
|
Note: Synchronize for UNIX is distributed as a single 3 to 6 MB tar image (7 to 10 MB after installation) and contains a sample database.
* varies by platform |
||||
|
CyberScheduler |
RAM |
Disk space |
Virtual memory |
Other requirements |
|
Web server |
Minimum recommended by OS |
0.5 MB |
Minimum recommended by OS |
Must support HTML forms with GET and POST CGI methods. |
|
Web browser |
Minimum recommended for browser |
Minimum for browser |
If necessary |
HTML 2.0, Java Script capability recommended. |
|
Note: A Synchronize server for UNIX (version 1.3 or above) must be installed and running. |
||||
Installing the Synchronize 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 server 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. Edit the
db/users file to add the users who will be using Synchronize. See the Users and Groups section of the Synchronize System Administrator’s Guide for details.4. Start the Synchronize server by typing:
platform
/bin/synchrod5. At this point, you are done installing the server. You can proceed with installing CyberScheduler now.
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.
Where to Install
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.
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 server startup script (synchrod.sh) in the bin subdirectory allows 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 from a Downloaded File
If you have downloaded 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_fileto 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:
|
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 |
|
arch .new/ |
Platform-specific executables and support files |
|
ps.new/ |
Support files for PostScript® printing |
|
relnote |
Release notes |
|
resources.new/ |
Synchronize resource files including X resource files, help and message catalogs |
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. 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.
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.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.
If you are installing Synchronize for the first time, then you will be prompted to enter your license number.
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 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 (except root) to own the Synchronize hierarchy.
The installation program will offer to create three symbolic links for you. 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.
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 three 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.
After Installation
If you have installed the server and database, 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.
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. 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. Stop the Synchronize server operating on the 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.
Installing CyberScheduler
The Synchronize CyberScheduler release for UNIX is distributed with both a web server component and a CyberScheduler daemon component. The web server component is installed on your web server host, and the CyberScheduler daemon component is installed on your Synchronize server host.
If you do not have sufficient access to the web server host, you may wish to ask your webmaster to install the web server component for you.
Installation Summary
1. Extract the Synchronize CyberScheduler release from the media or tar image provided.
a) When installing the Web server component only, you should extract the release into any temporary directory (e.g., /tmp) on your Web server host and run the installation program there.
b) When installing the CyberScheduler daemon component only, you should extract the release into your existing Synchronize directory (e.g., /usr/local/lib/synchronize) and run the installation program there.
c) If the same machine hosts both your Web server and your Synchronize server, then you may install both components at the same time. When installing both components at the same time, you should extract the release into your existing Synchronize directory and should run the installation program there.
2. Run the installation program, e.g.,
sh ./WEBINSTALL
3. When asked which component you wish to install, enter "w", "d" or "b" to indicate which component(s) you wish to install, Web server component, CyberScheduler daemon component or both, respectively.
4. Depending on which components are being installed, you will be asked various questions. When prompted, enter the information requested.
5. The installation will report success or failure for each component separately. For example, if installation of the web server component failed for some reason, but the Synchronize server component installed successfully, then you need only worry about reinstalling the web server component.
There are two components included in the CyberScheduler software:
There are three possible scenarios that will determine if you will need to download one or two platforms for the CyberScheduler software.
Scenario 1:If you plan to install the Synchronize server software on the same host as your web server software, then you will only need to download one release of the CyberScheduler software corresponding to that host's platform.
If you plan to install the Synchronize server software on a machine which does not host your web software but this host and your web server are of the same platform type, then you will only need to download one release of the CyberScheduler software corresponding to your platform.
If you plan to install the Synchronize server software on a machine which does not host your web server software and this host is of a different platform type than your web server host, then you will need to download two releases of the CyberScheduler software, corresponding to each of those platform types.
Web Server Component
Installing this component of the software requires that you know a little bit about your existing web server configuration/layout. You should know the following details before beginning installation.
The installation will ask you to specify five directory locations where files should be installed. These include the following:
The installation will also ask you to specify the following additional information:
After installation, in order to log in through their browsers, users must have access to the login.html page (e.g.,
http://www.xyzcorp.com/synchronize/login.html) which was installed in the specified installation directory. You may wish to make the login.html page accessible from more than that one location by creating HTML links from other web pages or by creating symbolic links in other directories. CrossWind recommends that you keep the only real copy in the installation directory so that future updates of login.html are effected for all users.CyberScheduler Daemon Component
Installing this component is very simple compared to the web server component. The only requirement is that you extract the release into your existing Synchronize hierarchy. There are a total of three files which will be installed. These files are:
After installation of this component, you will need to do the following things to get up and running:
Running the Websyncd
1 . For each Synchronize server running on a particular machine, a different instance of the websyncd must be run on that machine to allow web access to the database for that Synchronize server.
a) If you are running the Synchronize server without a socketOffset option, run the websyncd the same way.
b) If you are running the Synchronize server with a non-zero socket offset (e.g., "synchrod -socketOffset N"), run the the websyncd the same way (e.g., "websyncd -socketOffset N").
2. The websyncd may be run in read-only mode, with the "
-ro" option. Users will be able to see their data, but any attempt to apply changes to the Synchronize server will result in a warning dialog and no application of those changes.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 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: 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.